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

[Levsha100]

В общем, рекомендую почитать книгу "С++ для профессионалов"(Н.Солтер, С.Клепер), там в главе 7, рассказывается про стиль кодо-писания

[JTG]

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

В RadStudio комментарии вида "//TODO: ..." и "//DONE: ..." подсвечиваются другим цветом и автоматически добавляются в ToDo-list. В нём и искать

[Arigato]

Если пишу на PHP какой-нибудь класс, то все public методы класса выношу в начало кода в виде комментария, перечисляю методы, аргументы к ним и краткое пояснение, для чего нужен тот или иной метод.
Когда забываешь, какие методы были в классе, открываешь описание класса и сразу видишь краткую справку.

[GenniY]

Если пишу на PHP какой-нибудь класс, то все public методы класса выношу в начало кода в виде комментария, перечисляю методы, аргументы к ним и краткое пояснение, для чего нужен тот или иной метод.
Когда забываешь, какие методы были в классе, открываешь описание класса и сразу видишь краткую справку.

Вот только один человек проник в суть вопроса.

Кто как считает, что лучше писать в блоке

PHP код:

{************************************************************}
{                                                            }
{                 Модуль ХХХ                                 }
{       Copyright (c) 2008  ООО ХХХХ                         }
{               отдел/сектор                                 }
{                                                            }
{  Разработчик: ХХ ХХ                                        }
{  Модифицирован: 11 октября 2008                           }
{                                                            }
{************************************************************} 


Или оставить так ка есть?

[Arigato]

Сообщение от GenniY

Или оставить так ка есть?

Если Вы сами разрабатываете эти модули, пишите то, что считаете нужным.
Если работаете в команде, посоветуйтесь лучше со своей командой, а не с нами.

[alexinspir]

Сообщение от GenniY

Спасибо.

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

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

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

Дополню пост crazy horse:

Сообщение от crazy horse

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

Уважаемый GenniY, что скажете на счет этого?

    /**
     * Returns an array containing all of the elements in this collection;
     * the runtime type of the returned array is that of the specified array.
     * If the collection fits in the specified array, it is returned therein.
     * Otherwise, a new array is allocated with the runtime type of the
     * specified array and the size of this collection.
     *
     * <p>If this collection fits in the specified array with room to spare
     * (i.e., the array has more elements than this collection), the element
     * in the array immediately following the end of the collection is set to
     * <tt>null</tt>.  (This is useful in determining the length of this
     * collection <i>only</i> if the caller knows that this collection does
     * not contain any <tt>null</tt> elements.)
     *
     * <p>If this collection makes any guarantees as to what order its elements
     * are returned by its iterator, this method must return the elements in
     * the same order.
     *
     * <p>Like the {@link #toArray()} method, this method acts as bridge between
     * array-based and collection-based APIs.  Further, this method allows
     * precise control over the runtime type of the output array, and may,
     * under certain circumstances, be used to save allocation costs.
     *
     * <p>Suppose <tt>x</tt> is a collection known to contain only strings.
     * The following code can be used to dump the collection into a newly
     * allocated array of <tt>String</tt>:
     *
     * <pre>
     *     String[] y = x.toArray(new String[0]);</pre>
     *
     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
     * <tt>toArray()</tt>.
     *
     * @param a the array into which the elements of this collection are to be
     *        stored, if it is big enough; otherwise, a new array of the same
     *        runtime type is allocated for this purpose.
     * @return an array containing all of the elements in this collection
     * @throws ArrayStoreException if the runtime type of the specified array
     *         is not a supertype of the runtime type of every element in
     *         this collection
     * @throws NullPointerException if the specified array is null
     */
     <T> T[] toArray(T[] a);

Как вы напишите аналогичное? Напишите своими кракозябрами от которых Разработчиков в с реальным, "боевым" опытом, будет просто тянуть блевать с мыслью "что *** за блондинка этот код писала?!"?

[mutabor]

Я считаю важна информация к-рая в блоке, а не то как он оформлен, звездочками или пунктиром или еще как. Главное чтобы он был отделен от кода и хорошо читался.

Честно говоря я когда прокручиваю исходник в самый верх с целью просмотреть заголовочный блок, спроси меня после этого - а с помощью чего он был выделен - я не отвечу, т.к. мне это пофиг, а вот если он сливается с кодом модуля и его попросту неудобно читать то на это внимание сразу обращается.

Модули называть нужно так, как это принято в команде если ты присоединился к разработке. Стиль элементарно определяется просмотром названий уже имеющихся модулей.

[alexinspir]

Сообщение от mutabor

Я считаю важна информация к-рая в блоке, а не то как он оформлен, звездочками или пунктиром или еще как. Главное чтобы он был отделен от кода и хорошо читался.

Честно говоря я когда прокручиваю исходник в самый верх с целью просмотреть заголовочный блок, спроси меня после этого - а с помощью чего он был выделен - я не отвечу, т.к. мне это пофиг, а вот если он сливается с кодом модуля и его попросту неудобно читать то на это внимание сразу обращается.

Модули называть нужно так, как это принято в команде если ты присоединился к разработке. Стиль элементарно определяется просмотром названий уже имеющихся модулей.

Убило

Образец комментария, который я показал в перыдущем посте, создаст вот такую документацию, 1 в 1:
http://java.sun.com/javase/6/docs/ap...y%28T[]%29
Цель комментариев такого типа не тупо обьяснить в коде что он делает, но и создать описание методов/классов/пакетов/полей классов и тд и тп для библиотеки классов, исходный код к которой распрастранять не предполагается.
В общем - создание документации для разработчиков, т.е. для тех кто будет после тебя работать с твоим кодом, либо для тебя самого, по прошествии времени.

[mutabor]

2 alexinspir, Вообще-то автор темы спрашивал о заголовочном блоке модуля, а не о комментариях к коду. А ваши посты я вообще не имел ввиду, а отвечал автору темы.

[Vol666]

Никак не подписываю, вообще ноль оформления, голый код тупо в столбец.