Как подписываем модуль.

[AnTe]

Сообщение от Alex Cones

У дельфи IDE в эдиторе есть вертикальная линия справа, за ней я оставляю свои ремарки в случае, если нужно "доделать" код.

да, кстати, есть какая-то серенькая линия. А зачем она? при написании за ней всё воспринимается компилятором как текст программы, или это было в смысле писать там комментарии, т.е. с // или {} или (**) ?

главный вопрос, как потом искать то, что "нужно доделать". Иногда модуль не на одну тысячу строк размером.

[crazy horse]

2alexinspir Совершенно верно, нечего велосипеды изобретать. Есть вполне общепринятые ASDoc, Jdoc... ну и их аналоги под конкретные языки.

[GenniY]

Меня интересует ваше мнение по поводу того,как прозывать модуль?

Модуль ХХХ

С чего он должен состоять?

Например: Сокращ. название организации,дальше идет отдел и потом уже название самого непосредственно модуля. Так советую во многой документации.

Но я считаю, например, что название отдела (хоть и сокращенное) не должно быть. Оно указывается ниже. Непосредственное название модуля также повторяется дважды: в

Модуль ХХХ

и в

unit

.

Этот

Copyright (c)

Вообще нужно убрать. Он никакого смысла вообще не несёт

[crazy horse]

Название должно соответствовать задачам модуля. И точка.

[Stilet]

генератор заголовков!

Я писал когда-то такой на Мульти-Эдите. Ну там я не только заголовки генерил, а еще и оформление кода делал. Ключевые слова - UpperCase, К функциям комменты добавлял...

[GenniY]

генератор заголовков!

Конечно, можно пользоваться готовыми шаблонами, но верны ли они?

Хотелось бы разработать единственный и правильный экземпляр заголовка модуля.

Это нужно когда берешь код твоего бывшего коллеги и в ближайшее время нужно переделать. Но не можешь понять —это действительно тот код или всего лишь часть, да и вообще—это его ли. А ещё в папке с программой лежат, например, непонятные модули. Может он ими временно пользовался или думал пользоваться или просто случайно скопировал.

А так можно было бы посмотреть в заглавный и последующие модули и четко понять—что и как использовать. Но чтобы это было не просто набросано, а читабельно разложено по полочкам.
Если большие программы это очень хорошо помогает.

Друзья, я так и не пойму, что никто не использует определенных (даже своих) стандартов в своей организации. Что всё пишется по старинке —"потом разберусь..."? Я так не думаю...

[crazy horse]

Еще раз: http://jsdoc.sourceforge.net/ Чем не устраивает? Мало того, она еще и доки генерит по нему. Спецификации по-моему сейчас для практически всех языков есть.

[GenniY]

Еще раз: http://jsdoc.sourceforge.net/ Чем не устраивает?

Спасибо.

Но я даже ставить передумал, когда увидел примеры.
Вот, например:

   /**
              * Get the radius of this circle 
              * @returns The radius of this circle
              */
                   function Circle_getRadius(){
                     return this.radius;
                   }

1. Для чего поставлено так много "*"? Каким образом получается так что комент в 2 строки занимает 4!!!
2. Да и вообще—кому нужен такой комент! Название функции само говорит за себя.

Можно написать:

PHP код:

function GetCircleRadius(){
return this.radius;} 


Всё!!! Больше ничего не надо.
Вот над этим, ребята, как раз и надо работать. Не нужно пользоваться готовыми, но не точными шаблонами. Нужно сделать свое и правильное. Мы же не роботы: "скопировал-вставил" и забыл. Компилятор та поймет если мы всю программу напишем в одну строчку. А мы?

Может на это вопрос дизайнеры чего подкинут...

[crazy horse]

Это называется самодокументируемый код. Спасает от огроммного геморроя при поддержке и модификации. Ставить ничего не обязательно, и да, ты прав! К черту международные стандарты, будем лепить как хотим, нам никто не указ. Только не надо потом удивляться почему 1с бредприятие работает так, словно его гастробайтеры писали.
Зы. Коммент этот, уважаемый, нужен к примеру тогда когда я отладочным браузером щупаю функцию в каком-нибудь скрипте, то я на экране у себя вижу что ей нужны за параметры (браузер понимает эти вещи) и чего она мне вертает. И к чему обращается. И что в комментах. Так же как эти теги работают во время обращения к функции класса из другого модуля. IDE их подхватывает и показывает всплывающие подсказки как в библиотечных классах. Надо было не выхватывать из контекста, а хотя бы напрячься и почитать, там все описано.

[GenniY]

К черту международные стандарты, будем лепить как хотим, нам никто не указ.

Да причем здесь это? Конечно, стандартов придерживаться надо. Но не писать же заголовок

PHP код:

{*******************************************************}
{                                                       }
{       Borland Delphi Visual Component Library         }
{                                                       }
{       Copyright (c) 1995,98 Inprise Corporation       }
{                                                       }
{*******************************************************}

unit Buttons; 


А это предлагаемый Borland стандарт.
Для чего он такой вообще нужен?