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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

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

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

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

// 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

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

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

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

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

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

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){ ... }  

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

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

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

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

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

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

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

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

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

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

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

Код может (и должен) «самодокументироваться», но если вам нужно прочитать и понять каждую строку кода, чтобы понять, как работает метод. 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 - Должны ли мы добавлять комментарии после блоков кода, а не раньше? ..

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

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

    // 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");

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