Я видел это в SO Tavern , поэтому я размещаю вопрос здесь. Я подумал, что это интересный вопрос. (Конечно, это не относится к SO, но я думаю, что здесь все в порядке.)
Добавляете ли вы точки (или, как писал ОП, «полные остановки») в комментарии к коду?
Чтобы это было актуально, зачем ?
Ответы:
Полная остановка предназначена для окончания предложений, но если комментарий состоит только из одного предложения, окруженного кодом, то, по моему мнению, полная остановка не нужна. Иногда я даже не пишу с заглавной буквы первую букву. С другой стороны, подробный многострочный комментарий требует полной пунктуации.
источник
Да, потому что комментарии на английском, а правильный английский использует знаки препинания.
источник
Добавляете ли вы точки (или, как писал ОП, «полные остановки») в комментарии к коду?
Чтобы это было актуально, зачем?
По той же причине я добавляю их при написании «нормального» текста - они являются частью письменного языка, и в них не должно быть ничего особенного. Я использую их одинаково при написании комментариев (одной строки) и целых абзацев.
Исходный код не является обычным текстом, и поэтому мы используем разные правила для него. Просто ;-)
источник
Если вы пишете комментарии, можно надеяться, что они написаны на английском языке. В таком случае, следует правильно акцентировать внимание. Делать иначе было бы лениво.
источник
Если я напишу полное предложение (или больше), тогда да. Если нет, то иногда нет, но обычно все еще да.
Я также иногда схожу с ума и использую восклицательные знаки, знаки вопроса и т. Д .;)
Что касается того, почему, это отчасти потому, что я такой особенный, а отчасти потому, что я считаю, что соответствующая пунктуация может добавить много ясности.
источник
Другие ответы и их популярность прояснили, что в более длинных комментариях хорошо ценятся точки остановки, и, вероятно, их можно избежать в однострочниках.
Еще один момент, который может иметь значение, - это избегать восклицательных знаков, особенно кратных . Пример:
а также
С другой стороны, вопросительные знаки иногда очень полезны:
источник
Это зависит. Если я напишу большой правильный параграф, объясняющий, что делает блок кода, то я выделю его правильно, как и любой другой фрагмент правильного написания. OTOH, когда я просто комментирую одну строку кода, тогда я этого не делаю.
Зачем? - Подобно тому, почему я пишу электронные письма, используя правильное написание, в то время как я мог бы использовать сокращенные предложения в SMS-сообщениях. В одном случае я сижу, чтобы написать правильный блок текста, поэтому я просто автоматически «делаю это правильно», в то время как в другом это просто краткая заметка, чтобы донести смысл.
Реальные примеры из моего кода:
Быстрый комментарий к заметке:
«Правильный» метод документации:
источник
Да, я думаю, что таким образом вы создаете хорошее соглашение о кодировании, а также создаете аккуратный читаемый код для третьего лица, просматривающего ваш код.
источник
Я всегда буду использовать правильные прописные буквы и знаки препинания при создании комментариев XML, которые я ожидаю увидеть в IntelliSense и в нашей сгенерированной документации . Это гораздо более формальные конструкции и должны рассматриваться как таковые.
Однако комментарии, только что увиденные в теле блока кода, должны быть как можно более четкими. Программисту решать, как они этого добиваются.
источник