Как вы пишите комментарии в коде, как выделяете комментариями программные блоки?

Question

[Дмитрий]

Решил задать такой немного необычный вопрос.
У меня уже давно сложилась система написания комментариев в коде (будь то программа на php или просто html-верстка), причем речь идет именно о выделении комментариями различных блоков.
К примеру, открывается if ( ) { и где-то спустя сотню срок кода, закрывается.
Я обычно делаю так:

// проверка переменной на равенство 0 -------------
if ($x==0) {
   ...
}
//  / проверка переменной на равенство 0 -------------

Т.е. в начале блока (условие, цикл и т.д. или просто какой-нибудь блок кода, который нужно выделить) я пишу
комментарий (например, название блока или описание того, что в нем делается) а в конце блока (после закрытия фигурной скобки) тот же самый комментарий, но с обратным слешем, который указывает на то, что тут блок заканчивается.
Хотел узнать у сообщества кто еще какие приемы использует для подобной задачи. Может есть какая-то более удобная схема.

Answer 1

[Melkij]

и где-то спустя сотню срок кода, закрывается.

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

Answer 2

[Виталий Желтяков]

Использую следующее выделение блоков. Звёздочки для отдельных модулей, дефисы для отдельных функций. Длина такой строки 80 символов. В результате код наглядно разделён.

//**************************** Служебные функции *****************************//
//------------- Функция поиска свободного id в массиве  ----------------------//
function GenId() {
   var i = 0;
   while(arr[i]) {i++;}
   return i;
}
//----------------------------------------------------------------------------//
//****************************************************************************//

Comments

[Eugene Obrezkov]

Вот за такие комментарии и по рукам можно получить :)
Ну почему не писать бы по стандартам? Не забываем о camelCase и т.п.

/**
* This function do this
* @param {Object} param1 This param contains this
* @param {String} param2 This param contains string
* @returns {Mixed} Returns result
*/
function genId(param1, param2) {
return isString() && 'mixed';
}

[Facetrollex]

@VitaZheltyakov че курил? :)

[Виталий Желтяков]

@ghaiklor Какие это ещё стандарты? Те, которых Вы придерживаетесь?
@Facetrollex Если не понимаете в чём фишка, то проходите мимо.

[Eugene Obrezkov]

@VitaZheltyakov очень тщательно учим JavaDoc и JSDoc. Да, стандарты которых я придерживаюсь. А еще процентов 75 остальных программистов.

[Eugene Obrezkov]

@Facetrollex может его вариант внесем в документ и сделаем замену JSDoc? Смотрится неплохо :)

[Виталий Желтяков]

@ghaiklor Уберите свой сарказм - он смотрится глупо. JSDoc - это не стандарт.

[Eugene Obrezkov]

@VitaZheltyakov согласен. Эта модификация пошла от JavaDoc.
Согласен, стандартом это назвать нельзя.
Само собой, это ПО, которое генерирует документацию на основе комментариев.
А теперь давайте просто включим логику. Что будет более понятно другим программистам? Общепринятые комментарии, на основе которых спокойно генерируется полноценная документация или какие-то свои хитровыдуманные, плохо читаемые блоки комментариев, из которых и документацию не сделаешь?

Answer 3

[Андрей Унгер]

Тут опять-таки все продумано до нас. Все ваши функции и методы должны содержать минимум кода и выполнять ТОЛЬКО ОДНО действие. Если метод содержит более ~10 строк - его лучше разбить на два метода. Такие короткие функции и методы будут понятны без комментариев. Перед самым методом ставим комментарии чтобы их могла понять система автоматического дкументирования. Например:

/**
 * Метод делающий то-то
 * @param first первый параметр
 * @param second второй параметр
 * @return возвращаемое значение
 */

Answer 4

[Eugene Obrezkov]

Самая лучшая техника - это писать код, чтобы не комментировать. Само собой и код должен быть понятен :)
Я никогда не комментирую цельные блоки. Если нужно, то одной строчкой, не больше. Например:

if (null == null) {
    // If null == null then we need do this
} else {
    // If not I want something more
}

Answer 5

[Макс]

Если вы не пишите какой-то обучающий код, где надо разжевывать каждую конструкцию, то такие комментарии вообще излишни и усложняют чтение. Зачастую, вы в голове скомпилируете код быстрее, чем прочитаете комментарий. Разработчику с головой хватит аннотации к методу в стиле JavaDoc/PHPDoc. Комментарии внутри функции оправданы только для TODO или описания какой-нибудь хитрой магии, которые обычно пишут так, как сказал комментатор выше.

Answer 6

[SerCe]

Судя по вашему примеру вы в комментариях дублируете код, это неправильно, комментарий должен отвечать на вопрос - зачем? Программист код сможет и сам прочитать, а вот понять зачем...

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

Answer 7

[Facetrollex]

PhpDoc & etc.
Комментарии в коде только в очень не очевидных моментах. Хороший код сам себя комментирует

Answer 8

[Максим Углов]

Пишу смысл блока а не его действие
// -----проверка на ноли переменой $var
if($var==0) {

//......

}
пример бессмысленного комментария. лучше описать как данный код связан с внешним .
// $var количество записей, вывод похожих новостей

для хорошей визуализации делаю коменты в виде :
//================= $var количество записей, вывод похожих новостей =============

Answer 9

[Arris]

На больших блоках (например, jQuery или switch пишу как-то так (конечно есть отступы, но комментарии не вредят):

}); // end each()
}); // end bind

или

break; }; // end case
}; // end switch

или

// этот блок кода можно написать короче, но так понятнее и прозрачнее :)

Конечно, это может показаться избыточным :) Но во время разработки мне важнее мое удобство, а не компилятора :)

Answer 10

[MisterSpock]

Я пишу комментарии примерно как и Вы, но только на этапе разработки.

В финале я оставляю в коде комментарии только перед началом каждой функции или метода, если их назначение и параметры не очевидны с точки зрения кода, или если использовался определённый алгоритм.

Answer 11

[Mad-cote]

phpdoc.org