Комментарий до или после соответствующего кода [закрыт]

34

Предполагая, что комментарий не помещается (или не может идти) в строке, к которой он относится, следует ли писать комментарий до кода или после?

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

Так где же большинство программистов / сценаристов размещают комментарий: до или после его кода?

Если ваш ответ относится только к конкретным языкам, укажите, какие из них.

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

msh210
источник
3
Учитывает, что произойдет, когда вы положите его после Программист прочитал код. Скажи сам WTF это делает ??? Смотрите комментарий. Прочитайте код еще раз. Когда-нибудь поймешь это или сдайся. Так что будьте милыми и избегайте частей 1 и 2, поместив их сверху.
Deadalnix
@deadalnix, спасибо, похоже, в этом суть ответа Дипана Мехты . (Спасибо также всем ответчикам до сих пор и +1 каждому.)
msh210

Ответы:

22

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

Microsoft говорит, что было бы неплохо начать программирование с небольшого комментария. (Они не упоминают комментирование после процедур) MSDN Ссылка о VisualBasic, но она применима к большинству языков программирования, я думаю.

dasheddot
источник
1
Отметьте галочкой, поскольку это единственный ответ (пока что), который четко отвечает на вопрос, который искал не личные предпочтения, а стандартную рабочую процедуру, в которой он ссылается на MSDN.
msh210
1
@ msh210: То есть вы предпочитаете, чтобы Microsoft предпочитала личные предпочтения других хороших программистов? НО вы знаете, как Microsoft неправильно использовала венгерскую нотацию? Да? Вы? Только доверяйте здравому смыслу, не всегда бегайте с ордой или следуйте за самым большим быком.
Сокол
2
@Falcon, я никогда не слышал о венгерской нотации, и я подозреваю, что предпочтение MSDN было, по крайней мере, результатом множества комментариев сотрудников MS; Ответы здесь, напротив, создаются индивидуально.
msh210
43

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

Ryathal
источник
9

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

Джошуа Смит
источник
7

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

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

Дипан Мехта
источник
6

Так где же большинство программистов / сценаристов размещают комментарий: до или после его кода?

За многие годы программирования с использованием различных языков я не помню, чтобы какой-либо код встречался на каком-либо языке, где комментарий помещается в новую строку после кода, на который он ссылается. По крайней мере, в США стандарт де-факто комментирует либо перед кодом, либо в той же строке после кода. При написании ваших комментариев после соответствующего кода предлагается тест на наркотики, психиатрическое обследование и / или свидание с парой плоскогубцев и паяльной лампой.

Единственное исключение, о котором я могу думать, - это комментарий, отмечающий конец ранее прокомментированного раздела, например:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Джеф Раскин написал хорошо продуманное эссе о комментариях, которые стоит прочитать. Он не говорит, размещает ли он свои комментарии до или после кода, но он говорит, что никогда не помещает их в строку, и я бы поспорил на большие деньги, которые он не поместит после них.

Калеб
источник
4

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

При этом размещение может зависеть: если вы используете отдельную строку для комментария, поместите его перед реальным кодом. Если у вас есть это на той же самой линии, поместите это после.

// this workaround is required to make the compiler happy
int i = 0;

Против

int i = 0; // make the compiler happy

Но никогда:

int i = 0;
// this workaround is required to make the compiler happy

Лусеро
источник
Перечитайте вопрос: он указывает, что спрашивает о комментарии в отдельной строке.
msh210
2
@ msh210 Это идеальный ответ. msgstr "писать комментарии раньше". Это еще более подробно и дает возможную причину, почему вы можете подумать, что они после "За исключением случаев, когда они короткие и находятся в конце строки".
Rds
3

Я на самом деле не большой поклонник комментариев. Во время курса разработки программного обеспечения меня познакомили с идеей самодокументируемого кода. Код является единственной гарантированной на 100% правильной документацией - комментарии должны быть обновлены, тщательно составлены и актуальны, в противном случае они являются ловушками, которые могут быть хуже, чем отсутствие комментариев. Только когда я начал работать в магазине C ++ со строгим руководством по стилю и осмысленными соглашениями об именах, я действительно усвоил эту концепцию.

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

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

Брайан Стинар
источник
10
Самодокументированный код может отвечать «что» и «как», но независимо от того, насколько хорошо он написан, сам по себе код редко может отвечать на вопрос «почему?». Если есть исчерпывающий документ с требованиями, вы можете найти ответ там. В противном случае, комментарии - это все, что вам нужно, чтобы объяснить, почему код должен делать то, что он делает.
Эд Стауб
1
Я не согласна Как говорит @EdStaub, комментирование отвечает на другой вопрос, на другом уровне. Также код не обязательно с открытым исходным кодом. И даже когда это так, я не хочу читать исходный код фреймворка, чтобы знать, как его использовать.
Rds
4
Вы, очевидно, никогда не имели дело с аппаратным обеспечением (или взаимодействием с плохо написанным программным обеспечением, либо). Я недавно закончил писать специализированный класс, чтобы поговорить с довольно неясным (и капризным ) контроллером мотора. У этого есть все виды странных требований для взаимодействия. За исключением буквально одной функции в строке, невозможно сделать код понятным без комментариев.
Фальшивое имя
3
@ Брайан, вопросы «почему» часто очень детализированы - например, обойти ошибки в API и / или объяснить, что что-то, что выглядит неправильно, на самом деле правильно. Это всего лишь пара примеров. Я бы не стал комментировать документ с исчерпывающими требованиями. Но я также не буду пытаться объяснить обоснование каждой маленькой детали реализации в спецификации требований (или даже в спецификации проекта).
Эд Стауб
1
@codesparkle - я согласен, что комментарии, используемые как оправдание, чтобы избежать рефакторинга, как правило, плохие. Однако это не означает, что все комментарии плохие, просто комментарии, которыми злоупотребляют таким образом, являются. Дело в том, что существует ряд ситуаций, когда комментарии действительно являются лучшим вариантом для разъяснения нечетных требований к кодированию.
Фальшивое имя
2

Наличие комментария перед тем, как код помогает читателю иметь контекст для кода, с которым они собираются столкнуться. Гораздо гуманнее, чем бросать на них код и объяснять, когда они уже запутались.

Дэн Рэй
источник
2

Хорошо, я сделаю случай «после»: код всегда должен быть основной документацией, в то время как комментарий (который не имеет семантического значения) подобен объяснению в скобках. Таким образом, размещение комментария под кодом, который требует объяснения, оставляет код в качестве основного объяснения и просто использует комментарий для пояснения. Например,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

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

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  
Ларри Обриен
источник
5
Оба ваших блока кода имеют комментарии перед кодом, который они комментируют.
msh210
Ваши собственные комментарии сводят на нет ваши «после дела» хехе :) объятия и +1 за то, что сделали его примером на рождественскую тему
Ахмед Масуд
1
@ msh210 Я вижу, что мои комментарии в первом примере комментируют тест if (christmas), а не как «о» следующих функциях (то есть они говорят «что это значит, что мы здесь?»). Они предшествуют блок кода, но я никогда не видел код, который имел бы ... code (); код(); / * комментарий, поясняющий предыдущий блок * /} и не отвечающий на этот вопрос
Ларри OBrien
1

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

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

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

Томас Оуэнс
источник
1

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

К счастью, комментарий может идти выше или ниже фрагмента кода и, тем не менее, не оставляет сомнений относительно того, к какому фрагменту кода он относится, благодаря правильному использованию пустых строк. Конечно, программисты, которые не обращают внимания на использование пустых строк, не поймут, о чем я говорю; если вы один из них, пожалуйста, пропустите этот ответ и продолжайте свою жизнь. Но программисты, которые обращают внимание на пустые строки, прекрасно знают, что пустые строки используются для разделения кода на логические объекты. Итак, если вы видите следующее:

[blank line]
/* comment */
{ code }
[blank line]

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

[blank line]
{ code }
/* comment */
[blank line]

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

Майк Накис
источник
Как я всегда говорю: ваш пониженный голос без объяснения причин не помогает мне стать лучше. Тоже люблю тебя!
Майк Накис
1

Комментарии выше лучше.

если вам нужно включить комментарии, а ваш код не требует пояснений, то я бы не стал смущаться блоком кода, а затем посмотрите «ааа, это то, что он должен был сделать».

Код может (и должен) «самодокументироваться», но если вам нужно прочитать и понять каждую строку кода, чтобы понять, как работает метод. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Когда я размышлял об этой теме, я обнаружил, что большинство машиночитаемых систем документации (Doc XML, Doxygen, Java doc и т. Д.) Ожидают, что комментарий придет раньше, чем код, к которому он относится - лучше оставаться совместимым с этим стандартом.

Я также согласен с темой SO - Должны ли мы добавлять комментарии после блоков кода, а не раньше? ..

Я также предпочел бы знать заранее ...

Ниранджан Сингх
источник
1

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

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Дополнительным преимуществом является то, что когда дела идут плохо, я могу включить трассировку журналов и получить более подробный журнал выполнения.

комар
источник