Предполагая, что комментарий не помещается (или не может идти) в строке, к которой он относится, следует ли писать комментарий до кода или после?
Хорошо, где будущие читатели будут лучше понимать сферу действия комментария. Другими словами, везде, где большинство программистов / сценаристов размещают такие комментарии.
Так где же большинство программистов / сценаристов размещают комментарий: до или после его кода?
Если ваш ответ относится только к конкретным языкам, укажите, какие из них.
И если вы можете сослаться на принятую спецификацию или руководство, которое поддерживает ваш ответ, тем лучше.
Ответы:
Я бы прокомментировал или встроенный код, или перед кодом, к которому должен применяться комментарий. Смысл комментариев состоит в том, чтобы получить некоторое общее представление о том, что делает код, без необходимости читать сам код. Поэтому гораздо разумнее размещать комментарии перед кодом, который он описывает.
Microsoft говорит, что было бы неплохо начать программирование с небольшого комментария. (Они не упоминают комментирование после процедур) MSDN Ссылка о VisualBasic, но она применима к большинству языков программирования, я думаю.
источник
Я предпочитаю, чтобы комментарии были выше кода, на который они ссылаются, просто имеет смысл рассказать человеку, читающему код о происходящем, вместо того, чтобы пытаться ссылаться на предыдущий код, чтобы объяснить, что некоторые беспорядочные строки кода исправили некоторую хитрую ошибку так что не трогай это.
источник
Я думаю, что код обычно читается сверху вниз. Если бы не что-нибудь еще, мышечная память заставила бы меня связать комментарий со следующей строкой кода под ним.
источник
Как правило, комментарий должен быть в верхней части строки после того же отступа, что и работа. Например, комментарии выше тела функций, а один вкладыш - чуть выше начала критического алгоритма.
Причина в том, что когда кто-то начинает читать это, становится очевидным вопрос, почему что-то делается таким образом; где, поскольку человек не знает, до какой точки нужно прокручивать ответ. Если это сверху, это прямо там, чтобы увидеть.
источник
За многие годы программирования с использованием различных языков я не помню, чтобы какой-либо код встречался на каком-либо языке, где комментарий помещается в новую строку после кода, на который он ссылается. По крайней мере, в США стандарт де-факто комментирует либо перед кодом, либо в той же строке после кода. При написании ваших комментариев после соответствующего кода предлагается тест на наркотики, психиатрическое обследование и / или свидание с парой плоскогубцев и паяльной лампой.
Единственное исключение, о котором я могу думать, - это комментарий, отмечающий конец ранее прокомментированного раздела, например:
Джеф Раскин написал хорошо продуманное эссе о комментариях, которые стоит прочитать. Он не говорит, размещает ли он свои комментарии до или после кода, но он говорит, что никогда не помещает их в строку, и я бы поспорил на большие деньги, которые он не поместит после них.
источник
Попробуйте комментировать только там, где это действительно необходимо; код должен стараться быть самодокументированным, когда это возможно.
При этом размещение может зависеть: если вы используете отдельную строку для комментария, поместите его перед реальным кодом. Если у вас есть это на той же самой линии, поместите это после.
Против
Но никогда:
источник
Я на самом деле не большой поклонник комментариев. Во время курса разработки программного обеспечения меня познакомили с идеей самодокументируемого кода. Код является единственной гарантированной на 100% правильной документацией - комментарии должны быть обновлены, тщательно составлены и актуальны, в противном случае они являются ловушками, которые могут быть хуже, чем отсутствие комментариев. Только когда я начал работать в магазине C ++ со строгим руководством по стилю и осмысленными соглашениями об именах, я действительно усвоил эту концепцию.
Иногда комментарии необходимы. Часто тщательное именование переменных, осмысленное использование пробелов и группировок, а также значимая логическая организация самого кода исключают необходимость в комментариях.
Это действительно отрицание притворства и обоснованности вашего вопроса, в отличие от ответа на вопрос, который у вас был. Я все еще думаю, что это актуально и может помочь вам, и я не был придурком. Если нет, то -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 - Должны ли мы добавлять комментарии после блоков кода, а не раньше? ..
источник
Я часто конвертирую комментарии (как мои, так и написанные другими) в записи журнала уровня трассировки. Как правило, это значительно облегчает понимание того, где его разместить.
Дополнительным преимуществом является то, что когда дела идут плохо, я могу включить трассировку журналов и получить более подробный журнал выполнения.
источник