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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

а также

    // This code really sucks!

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

    // TODO: What does Crojpler.bway() actually do?

Это зависит. Если я напишу большой правильный параграф, объясняющий, что делает блок кода, то я выделю его правильно, как и любой другой фрагмент правильного написания. 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.

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

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

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