Які ваші думки щодо періодів / повних зупинок у коментарях до коду? [зачинено]

Я бачив, що це запитували в таверні "SO" , тому я тут публікую запитання. Я вважав це цікавим питанням. (Звичайно, це не належить до 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?

Це залежить. Якщо я записую великий, належний абзац, в якому пояснюється, що робить блок коду, то я його пунктуюю належним чином, як і будь-який інший фрагмент належного написання. ОТО, коли я коментую лише один рядок коду, тоді я цього не роблю.

Чому? - Подібно тому, чому я пишу електронні листи, використовуючи належне написання, тоді як я можу використовувати скорочені речення у 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 та в нашій створеній документації . Це набагато формальніші конструкції, і їх слід розглядати як такі.

Щойно помічені коментарі в коді блоку коду, однак, повинні бути просто максимально зрозумілими. Це залежить від програміста, як вони цього досягають.