Как нужно комментить свои программы?

Как правильней?

Понятный код > тесты > комментарии.

То есть комментарии вообще пишутся в конце, когда все функции отлажены? Или написал часть функций, все устраивает - взял откомментил?

В идеале, код должен быть понятен без комментариев. Комментарии могут быть нужны только к API, да и его лучше стремиться проектировать так, чтобы без лишних слов ясно было :)

ИМХО не считая очевидных глупостей, вроде прибавляем единицу всё остальное допустимо.

Лично я придерживаюсь следующих правил:

• комментарий к подпрограмме, в современных ide, всплывает в месте вызова под мышкой (ну или ещё как отображается). Поэтому я его делаю коротким и по делу.
• стараюсь комментировать значимые объекты. Простыни в начале файла всё равно никто не читает.
• вовсю использую принцип самодокументирования. Аргумент с понятным именем лучше, чем любое описание (а не как ты привёл a,b,c).
• писать отдельную документацию мне лень, кроме того проекты обычно крупные, так что я делаю так:
  • вкратце комментирую шаги алгоритма внутри тела особо оформленными комментариями;
  • грепаю эти комментарии и делаю из них tex файл (а потом и красивую pdf'ку). Всё, естественно автоматом.
  • на все вопросы отвечаю «документацию читали?»
  • ...
  • PROFIT!

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

Иногда без контекста в голове функция непонятно что делает и/или нафига это вообще, а иногда нетривиальна и не парсится сходу. Вот тогда я пишу каменты, сам для будущего себя. В остальном лучше называть все нормально, а то со временем будет классическое: в каментах одно, в коде другое. Смысл инвариантов может растекаться по исходнику, сразу все не поправишь. Иногда в начале модуля детально пишу как все устроено, а дальше и так ясно будет что происходит.

Когда в чужой или старый код смотришь, обычно вопрос не как, а нахрена? Это и надо объяснить.

В начале любых компонентов программы (модулей, методов, классов и т.д.) нужно писать внятный doc string, который сообщает, что данный компонент делает, какие структуры содержит, какие аргументы принимает, какие выдаёт результаты и т.д.

По ходу написания компонента нужно комментировать логически связанные куски, напр. «здесь читаем данные», «здесь вычисляем тензор Кругложопова» и т.д. Также надо комментировать куски, в которых сложно разобраться, типа «внимание, здесь может быть подвох в том-то и том-то».

А вообще, литературу в руки.

Начни с чтения книжек Совершенный Код (Code Complete, Макконнелл) и Рефакторинг (Фаулер). Есть, например, на рутрекере.

нужно ли по шагам описывать алгоритм

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

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

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

это (и другое) есть в литературе по TDD и BDD. Например, «Экстремальное программирование: разработка через тестирование» Кента Бека (есть на рутрекере)

«Склеивает три символа и отдает строкой»

это ОК, более точные параметры люди сами посмотрят по сигнатуре функции. В документации нужно отразить самую суть. В излишних подробностях суть исчезает (кроме того, начинается серьезное дублирование между кодом и комментарием).

Еще, очень советую вот этот пост Влада, четать до просветления: часть раз, часть два.

По ходу написания компонента нужно комментировать логически связанные куски, напр. «здесь читаем данные», «здесь вычисляем тензор Кругложопова» и т.д.

Феерическая ересь. Только слепой и безрукий инвалид не поймет что здесь мы читаем данные или что происходит при вызове calculate_roundass_tensor.

Убивал бы за такие комментарии, из-за них код расползается за экран, хотя мог бы замечательно помещаться.

Себя убей.

То есть комментарии вообще пишутся в конце, когда все функции отлажены? Или написал часть функций, все устраивает - взял откомментил?

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

+1 В том числе и за Code Complete, дельные советы содержит книжка.

Можно глянуть на ваш профиль на GH (или подобном ресурсе)? Или для себя ничего не пишете? Тогда может коммиты в OSS проекты?

// Так код «поясняют» только полные нубасики. Ну или если лабу кому-нибудь делаешь (о, как давно это было).

Бывает, что calc_rou... Не выносится в функцию, а вычисляется на месте, по пути захватывая нехилую часть контекста. Такие места неплохо отделять хотя бы простым \n//\n. Комментить каждое действие или блок конечно идиотизм, но некоторые языки просто бесят тем, что нельзя написать прям тут же локальную функцию с именем или просто по-честному поименовать кусок кода и выделить жирным ктрл-б важные места, или серым незначимые проверки/ассерты.

Можно глянуть на ваш профиль, ананимный балабол? Нет? Здрыстни тогда.

вычисляется на месте, по пути захватывая нехилую часть контекста

Refactor->Extract->Method не подойдет разве?

Бред все это, комментировать нужно только реально непонятные места. А так, можно скатится вообще до комментирования каждой строчки:

if (troll) { //Если troll равен true
while (true) { //начинаем в цикле
cout << "troll\n"; //выводить слово troll пока
                   //процессор не помрет...
}
}

Хороший топик.

Приписываю себя к быдлокодерам, но все же выскажу свое мнение.

1. Нужно стремиться к тому, чтобы код был понятен без комментариев. Этому способствует осмысленные названия функций/переменных, ну, и следование определенным правилам именования переменных/функций/... Расчитываем на человека с IQ over 90 (то есть не полных дебилов, но и не экстрасенсов).

2. В коде комментарии нужны там, где нужно объяснить логику операции, если это не понятно из кода, или чтобы обозначить какой-то логический блок, опять же, когда это улучшает понимание программы. Еще у меня есть пометки TODO и BUG - чтобы потом незабыть поправить. Например (ничего что C++?):

vector<unsigned char> numbers; // Array starts with 3 and has a step of 2: 3, 5, 7, 9 ...   //// Без комментария неочевидно

inline uint NumberToIndex(const uint number) {return (number-3)/2;}; // BUG: number should not be < 3

if ( numbers[NumberToIndex(head)]==1 ) { // Is prime/unchecked yet   //// Объясняет смысл условия
  if (!IsPrime(head)) { // Is not prime   //// Из кода логика понятна; это скорее обозначает логический блог
    numbers[NumberToIndex(head)]=0;
  }
  else{ // Is prime    //// Вот вторая часть логического блока
    /*********** Multithreading using OpenMP ***********/   //// У меня было много однотипных функций, отличающихся в основном этим участком - тестировал разные методы multithreading. Комментарий чтобы обратить внимание именно на этот участок.
    #pragma omp parallel
    {
      MarkNonPrime3(this,head,max);
    }
  }
}

void DeCrypt()
// Decrypting backward: simpliest method
{

void DeCrypt2()
// Decrypting forward
{

/*object*/ trips.ValidateDate=function(/*string*/ date)

Самый лучший код — это который write-only.

То есть, гордится тебе нечем, так и запишем.

Можно глянуть на ваш профиль

Какой же я после этого буду аноним? Там полный дискложуре, так сказать.

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

Бывает, что calc_rou... Не выносится в функцию

Ну тут или крестик, или трусы.

Убивал бы за такие комментарии, из-за них код расползается за экран

Убей ide, которая не умеет сворачивать документационные комментарии хоткеем

Но не переживай, все мы учились и были молокососами, в том числе и я.

Ну вот, и выяснилась правдаЪ. Если ты ананимный молокосос, то нахер ты встреваешь в диалог уважаемых людей? Иди, домашку делай, ананимный пионер, мля.

диалог уважаемых людей

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

Убей ide, которая не умеет сворачивать документационные комментарии хоткеем

Сначала одни мартышки эти камменты строчат, потом другие скрывают. Все заняты делом, идиллия, епт.

ну не ведро же конпелять, в самом-то деле

поблочно?

Я вообще не программист, но хочется плюсануть некоторые моменты из упомянутых в треде. В своих наколенных поделках стараюсь для себя придерживаться следующих правил:
быдлокодить читаемо;
именовать самоописательно;
комментировать ключевые моменты и то, что делают длинные и|или неудобочитаемые куски;
в некоторых случаях сначала описывать общий план в нескольких комментариях, а потом между ними быдлокодить (для пущей ясности в голове);
комментировать кратко, иначе проще код читать, а не комменты.
Если то же самое, но короче: код должен читаться и сам по себе, но там, где быстрее прочесть комментарий, он должен быть, краткий и понятный.

помнится, когда учился в универе, у нас был С++, и преподавательница, которая вела этот курс, комментировала код в таком духе)

while (...) // цикл while

{ ... }

Начни с чтения книжек Совершенный Код (Code Complete, Макконнелл)

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

Комментирую в стиле doxygen. Правда, комментировал не всегда: начал комментировать тогда, когда понадобилось модифицировать старый велосипед, а там было такое, что "без поллитры не разберешься".

Комментирую так: в шапке файла над текстом GPL — краткое описание содержимого; перед каждой функцией — описание функции и параметров (иногда даже полный текст алгоритма, чтобы понятней было); у структур в заголовочных файлах — описание полей; описание некоторых глобальных переменных и т.п.

помни правило: если этот участок кода нуждается в комментарии - подумайте о том что это первый кандидат на отдельный метод/функцию :)

literate programming

а могла бы рожать

Так она родила. Её сын вёл у нас Java))

если я ее откомментирую следующей строкой «Склеивает три символа и отдает строкой» - это дурной тон?

Фнукции называть надо так, чтоб из имени понятно было, что она делает. А комментировать к функции надо её передаваемые параметы, ограничения, с которыми функция принимает и обрабатывает параметры и что и в каком случае она выдаёт, если это не очевидно.
Я на сях не кодю, но когда кодил одну длинную вещь на баше, у меня были функции, которые вели себя немного по-разному в зависимости от того, кто эту функцию вызвал. За счёт встроенного в баш механизма отслеживания там, в глубине, проверяется только родитель, что позволяет избежать лишних переменных в роли флагов или передаваемых параметров функции. Однако снаружи двоякость поведения может быть неочевидна, поэтому лучше её описать там же, в комментарии.

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

Вообще словесное описание должно идти в каком-то README файле, ориентированном на конечного пользователя. Так проще всего въехать в то, что программа делает. Если README файла пока нет, я пишу зачатки сразу в коде, там, где, как мне кажется, становится пора что-то разжевать. Каждый файл должен иметь наверху строку с собственным именем и под ней пару слов (максимум — пару строк), о том какой функционал тут реализован. Дальше по коду, за исключением зачатков README файла, комментируются только те места, где смысл происходящего может быть неочевиден (какая-нибудь простыня сложных конструкций) или восприниматься двояко из-за схожести чего-то с чем-то. Также, в длинных скриптах я комментирую чекпойнты, когда какая-то длинная важная часть алгоритма завершена. Это делается для того, чтобы «расслабить» мозг, чтобы он мог не думать больше о тех функциях, они больше не понадобятся. Реально помогает. Ещё опасные участки кода помечаю комментариями, начианающимися с «W!». Когда надо что-то доделать ставлю «FIXME:», все этим места потом хорошо находятся. Их не должно быть много. Ключевое основание для существования комментария — неочевидность. Когда в чём-то сомневаешься, представь себя читающим свой код три года спустя. Сообразишь или нет? Или представь, что обсуждаешь свой код с кем-то. Если тебя спросят: «Зачем так, а не так?» — лучше ответить сразу в комментарии.

Да уж, регресс налицо: форк получился хуже ☺

или нужно изъясняется техническим языком

Если из-за этого понимаемость ухудшится — нет.

Это делается для того, чтобы «расслабить» мозг, чтобы он мог не думать больше о тех функциях, они больше не понадобятся. Реально помогает.

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

Всем большое спасибо за советы! Читаю, анализирую, думаю.