Что вы думаете о периодах / полных остановках в комментариях к коду? [закрыто]

27

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

Добавляете ли вы точки (или, как писал ОП, «полные остановки») в комментарии к коду?

Чтобы это было актуально, зачем ?

Моше
источник
2
Иногда я делаю, а иногда нет. Это зависит от комментариев и от того, что легко читать.
Тим

Ответы:

29

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

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}
mojuba
источник
4
+1. Это так похоже на мой стиль комментирования, что дало мне ложную дежавю. :)
Бобби Столы
26
Нет, точка останова - для обозначения конца предложений. Неважно, есть ли у вас один или несколько.
Ладья
2
<шутка> Не лучше ли было бы проверить, не превышают ли границы int? </ joke>
Дэн Розенстарк
2
@ Яр: среднее всегда между a и b, которые по определению всегда находятся в пределах границ, верно? ;)
Моджуба
8
Все мои строки заканчиваются нулем, поэтому правильный комментарий всегда должен заканчиваться на '\ 0'. Вы не хотите, чтобы следующий парень, смотрящий на ваш код, прочитал до конца его мысли?
CodexArcanum
26

Да, потому что комментарии на английском, а правильный английский использует знаки препинания.

Доминик Макдоннелл
источник
2
Как насчет текстовых сообщений?
Моше
4
@ Моше, текстовые сообщения вряд ли на английском.
Доминик Макдоннелл
8
Вряд ли правильный английский, но я все еще использую пунктуацию в них. Пунктуация предназначена для того, чтобы помочь читателю понять, что именно задумал автор - это относится к любому языку, ИМХО.
cjmUK
@cjmUK, Лол, да, и я тоже. Я думал, что Моше имел в виду причину, по которой мы не будем использовать пунктуацию, так как я регулярно получаю сообщения типа «что до свидания», которые толкают меня к стене
Доминик МакДоннелл
Я хочу, чтобы все было в порядке
cjmUK
17

Добавляете ли вы точки (или, как писал ОП, «полные остановки») в комментарии к коду?

Чтобы это было актуально, зачем?

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

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

ладья
источник
Мой друг никогда не запирает слова в электронных письмах ... потому что это в Интернете. Для меня это нормально, когда вы приспосабливаете свое письмо к техническим ограничениям, таким как SMS, но чем электронные письма или исходный код отличаются от текста в письмах и книгах?
LennyProgrammers
1
@ Lenny222 - Не уверен, что вы спрашиваете здесь. Письма должны быть написаны как обычный текст; как будто ты пишешь письмо, как говоришь. Как они на самом деле написаны (и СМС, о боже, не начинайте меня с СМС :) Исходный код не подчиняется тем же правилам, что и обычный текст, потому что он имеет свои собственные правила синтаксиса.
Ладья
2
Для меня комментарии к исходному коду предназначены для чтения людьми. Почему должно иметь значение, находится ли некоторая информация в отдельном документе спецификации или встроена в комментарий исходного кода?
LennyProgrammers
@ Lenny222 - Что-то произошло со мной, так что между нами нет недоразумений. Мы сейчас говорим об исходном коде или комментариях в нем? Если это второй случай, то я прошу прощения, потому что я неправильно понял вас. В этом случае действуют те же правила, что и для обычного текста (для комментариев). В реальном исходном коде (который читается компилятором / интерпретатором) я не вижу, как могут следовать те же правила.
Ладья
1
Да, я думаю, что мы согласны друг с другом, не зная. ;)
LennyProgrammers
9

Если вы пишете комментарии, можно надеяться, что они написаны на английском языке. В таком случае, следует правильно акцентировать внимание. Делать иначе было бы лениво.

quickly_now
источник
1
Периоды для конца предложения. Комментарии не обязательно являются полными предложениями.
Джон Б. Ламбе
Комментарии, как правило, должны быть предложениями. Если нет, я должен спросить, почему нет. Если ваши комментарии настолько короткие, что они не являются предложениями, возможно, они очевидны и потому излишни?
quick_now
5

Если я напишу полное предложение (или больше), тогда да. Если нет, то иногда нет, но обычно все еще да.

Я также иногда схожу с ума и использую восклицательные знаки, знаки вопроса и т. Д .;)

Что касается того, почему, это отчасти потому, что я такой особенный, а отчасти потому, что я считаю, что соответствующая пунктуация может добавить много ясности.

Адам Лир
источник
Если вы используете вопросительные знаки, понимаете ли вы свой собственный код?
Моше
@Moshe: Обычно это TODO, когда я еще не до конца понимаю свой собственный код.
Адам Лир
2
@Moshe - Почему комментарии не могут включать вопросы? Вопросы могут быть риторическими. На самом деле, я часто с нами? в моих комментариях - при описании условного кода, а не сухого объяснения логики, часто яснее описать логику как вопрос. Например, "Были ли выполнены квалификационные критерии? Если нет, выведите предупреждение пользователю".
cjmUK
1
Работая с большими проектами и многими соавторами, я часто нахожу эти вопросительные комментарии наиболее важными.
LennyProgrammers
3

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

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

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

а также

    // This code really sucks!

С другой стороны, вопросительные знаки иногда очень полезны:

    // TODO: What does Crojpler.bway() actually do?
Дэн Розенстарк
источник
1

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

Зачем? - Подобно тому, почему я пишу электронные письма, используя правильное написание, в то время как я мог бы использовать сокращенные предложения в SMS-сообщениях. В одном случае я сижу, чтобы написать правильный блок текста, поэтому я просто автоматически «делаю это правильно», в то время как в другом это просто краткая заметка, чтобы донести смысл.

Реальные примеры из моего кода:

Быстрый комментарий к заметке:

// check for vk_enter

«Правильный» метод документации:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.
Бобби Столы
источник
Разработчик .NET, а? ;-)
Моше
@Moshe: Java на самом деле. Это код из очень большого и сложного апплета, в основном как настольное приложение Swing, за исключением того, что он запускается в браузере. :)
Бобби Столы
Я думал, что MDI - это термин .NET.
Моше
@Moshe: нет, это универсально ( en.wikipedia.org/wiki/Multiple_document_interface ).
Бобби Столы
1

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


источник
1
Как насчет второго человека?
daviewales
0

Я всегда буду использовать правильные прописные буквы и знаки препинания при создании комментариев XML, которые я ожидаю увидеть в IntelliSense и в нашей сгенерированной документации . Это гораздо более формальные конструкции и должны рассматриваться как таковые.

Однако комментарии, только что увиденные в теле блока кода, должны быть как можно более четкими. Программисту решать, как они этого добиваются.

Мэтт ДиТролио
источник