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

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


Т.е. в начале блока (условие, цикл и т.д. или просто какой-нибудь блок кода, который нужно выделить) я пишу
комментарий (например, название блока или описание того, что в нем делается) а в конце блока (после закрытия фигурной скобки) тот же самый комментарий, но с обратным слешем, который указывает на то, что тут блок заканчивается.
Хотел узнать у сообщества кто еще какие приемы использует для подобной задачи. Может есть какая-то более удобная схема.
  • Вопрос задан
  • 4613 просмотров
Пригласить эксперта
Ответы на вопрос 12
Melkij
@Melkij
PostgreSQL DBA
и где-то спустя сотню срок кода, закрывается.

То это явный кандидат на рефакторинг.
Выделить всю сотню строк в функцию с явным кратким описанием в названии, что та делает.
Ответ написан
Комментировать
Использую следующее выделение блоков. Звёздочки для отдельных модулей, дефисы для отдельных функций. Длина такой строки 80 символов. В результате код наглядно разделён.
//**************************** Служебные функции *****************************//
//------------- Функция поиска свободного id в массиве  ----------------------//
function GenId() {
   var i = 0;
   while(arr[i]) {i++;}
   return i;
}
//----------------------------------------------------------------------------//
//****************************************************************************//
Ответ написан
Cobalt
@Cobalt
Программист - этим все сказано
Тут опять-таки все продумано до нас. Все ваши функции и методы должны содержать минимум кода и выполнять ТОЛЬКО ОДНО действие. Если метод содержит более ~10 строк - его лучше разбить на два метода. Такие короткие функции и методы будут понятны без комментариев. Перед самым методом ставим комментарии чтобы их могла понять система автоматического дкументирования. Например:

/**
 * Метод делающий то-то
 * @param first первый параметр
 * @param second второй параметр
 * @return возвращаемое значение
 */
Ответ написан
Комментировать
ghaiklor
@ghaiklor
NodeJS TechLead
Самая лучшая техника - это писать код, чтобы не комментировать. Само собой и код должен быть понятен :)
Я никогда не комментирую цельные блоки. Если нужно, то одной строчкой, не больше. Например:
if (null == null) {
    // If null == null then we need do this
} else {
    // If not I want something more
}
Ответ написан
Комментировать
zenwalker
@zenwalker
0xABADBABE
Если вы не пишите какой-то обучающий код, где надо разжевывать каждую конструкцию, то такие комментарии вообще излишни и усложняют чтение. Зачастую, вы в голове скомпилируете код быстрее, чем прочитаете комментарий. Разработчику с головой хватит аннотации к методу в стиле JavaDoc/PHPDoc. Комментарии внутри функции оправданы только для TODO или описания какой-нибудь хитрой магии, которые обычно пишут так, как сказал комментатор выше.
Ответ написан
Комментировать
@SerCe
Судя по вашему примеру вы в комментариях дублируете код, это неправильно, комментарий должен отвечать на вопрос - зачем? Программист код сможет и сам прочитать, а вот понять зачем...

Если отвлечься от содержимого примера, то в вашем примере есть проблема - дублирование, поменял в 1 месте, забыл в другом - и вот уже комментарии друг другу противоречат. Для разбивания кода на блоки используйте язык, а не комментарии.
Ответ написан
Комментировать
@Facetrollex
PhpDoc & etc.
Комментарии в коде только в очень не очевидных моментах. Хороший код сам себя комментирует
Ответ написан
Комментировать
niosus
@niosus
Если пишете сложный метод (такие бывают), то книжечка "Совершенный код" советует вообще написание метода начинать с комментариев. Запишите комментариями то, что хотите написать, потом заполните реальным кодом в нужные места между комментариев. После окончания - удалите очевидное. Профит.
Ответ написан
Комментировать
Пишу смысл блока а не его действие
// -----проверка на ноли переменой $var
if($var==0) {

//......

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

для хорошей визуализации делаю коменты в виде :
//================= $var количество записей, вывод похожих новостей =============
Ответ написан
Комментировать
Arris
@Arris
Сапиенсы учатся, играя.
На больших блоках (например, jQuery или switch пишу как-то так (конечно есть отступы, но комментарии не вредят):

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

или

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


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


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

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

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы