Що стосується коментарів щодо контролю версій, що роблять / рекомендують інші користувачі - минулий чи теперішній час?

Тобто

• Змінено x на y.
• або
• Зміна x на y.

Коментарі слід читати в контексті, тому:

Подарунок

Для коментарів джерела вище методу або до того, як відбудеться певна поведінка

// This function does X
function doX() { ... }

Минуле

Для коментарів джерел після певної поведінки

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

І для фіксації повідомлень

функція X змінена

Змішаний приклад:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Минуле - Оскільки кожен, хто читає його в майбутньому, посилатиметься на акт зміни, як це було раніше.

Якщо щось таке, як "Зміна", означає, що ви зараз перебуваєте в процесі внесення змін і що код може бути не закінчений.

Примітка: Особисто я вкладаю коментарі до змін лише тоді, коли відбулися кардинальні зміни.

Коментарі - це статичні речі, тому вони повинні представляти стан програми таким, яким він є , а не таким, яким він буде. Щоб відповісти на ваше конкретне запитання, було б доцільніше використовувати минулий час .

Однак цей тип коментарів краще підходить до вашої системи контролю версій. Контроль версій виконує набагато кращу роботу відстеження змін, ніж коментарі вручну. Що стосується систем управління версіями, то більш доцільним є документування в теперішньому часі, оскільки ці коментарі застосовуються в момент внесення змін. Але, або буде працювати.

Я настійно рекомендую, щоб єдиним коментарем у вашому коді було те, що потрібно для розуміння самого коду - мета, ділова логіка та виняткові випадки. Залиште документацію набору змін у вашій системі контролю версій. Якщо ви не використовуєте VCS, почніть зараз. Є кілька високоякісних VCS, які є безкоштовними (Subversion, Mercurial, Git тощо).

Я використовую імператив справжнього часу, так що:

Змініть "x" на "y"

Це рекомендують розробники Git:

• орган повинен надати змістовне повідомлення про вчинення, яке:
  • використовує імператив, теперішній час: "змінити", а не "змінити" або "змінити".

Спочатку це може здатися дивним, але якщо ви вважаєте, що комісія є виправленням, яка щось робить, це має більше сенсу. (Особливо це стосується DVCS типу Git, де ви перетягуєте набори змін у інших людей, які діють на ваш репо.)

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

Коментарі до коду повинні бути природними для читання.

Якщо ви читаєте код , говорите собі «Цей код буде робити X» , то ви повинні написати коментар в даний час , як це, ймовірно , як хто - то читає код в той час буде думати , як добре. Якщо з іншого, якщо ви думали в певний момент "Цей код зробив X", це повинно минути час. Зрештою, це зводиться до особистих уподобань, якщо з якоїсь причини ви не вказуєте, як коментувати свій код (тобто для командного проекту чи для класу тощо).

Якщо ви використовуєте git, умовою є використання поточного часу, оскільки повідомлення комісій, створені інструментами git (наприклад, злиття), використовують поточний час.

Вам слід скористатися минулим часом.

Причиною ви є те, що ви відповідаєте на питання, чого досягнув цей вчинок? Подумайте про це, як сказати вашому ДКС, що ви зробили:

Здійсніть 123
Змінено XYZ, щоб зробити ABC

Якщо навести зустрічні приклади, використання майбутнього часу дає змогу звучати так, ніби ви просите когось іншого зробити:

Введіть 123
Змінення XYZ на ABC

а за допомогою поточного напруженого звучить так, ніби ви перебуваєте на півдорозі:

Зробіть 123
Зміна XYZ, щоб зробити ABC

Використовуйте теперішній час: "Змініть X на Y" майже так, як якщо б це був предмет із чіткого списку TODO.

Взагалі, як і сценарій, уникайте дієслів типу "бути" і "є". Наприклад, це не «він ходить», а «він ходить».

Але в цьому конкретному прикладі - якщо ви говорите про коментарі до коду, а не коментарі до реєстрації - я вважаю, що "Змінити X на Y" - це жахливий коментар. Він не додає нової інформації, і якби код змінився, він може бути навіть неправильним. Краще, якщо ви витягнете код в метод (або клас), а потім замість цього документуєте. Якщо це досить зрозуміло, буде достатньо лише гарного імені методу.

Якщо говорити про те, що для методів документування ви можете використовувати майбутній час, наприклад: "Якщо подане число від'ємне, absповернемо величину числа".

Коментарі є (або повинні бути), як і все написане, виразом чогось, і вони повинні просто слідувати тим самим правилам на природних мовах (з урахуванням скорочень і скорочень, характерних для ситуації або артефакту, який задокументується.

Коментарі до теперішнього часу (тобто "воно змінюється" або "воно змінюється" ) свідчать про те, що на частину даних, якою керується задокументований алгоритм, якимось чином впливає. Тобто він вказує, що робить код або що відбувається з даними, якими обробляються дані.

Коментарі в минулому часі повинні вказувати на твердження, передумову або постулат того, що сталося до моменту перебування коментаря. Наприклад:

Введення вже було підтверджено до введення цього блоку коду

або

Дані були записані для зберігання в кінці цього коду, який виконується

Коментарі в минулому часі також можуть пояснити, чому щось робиться ( ця функція робить X і Y для вирішення проблеми зі спадковою базою даних. )

Коментарі в минулому часі, що вказують на зміну самого коду (.ie. X було змінено на Y ), не повинні існувати в коді. Натомість вони повинні існувати як коментарі до редакції у сховищі вихідного коду.

Коментарі в майбутньому повинні вказувати на умову, яку потрібно виконати або вирішити, але це з причини X або Y зараз не робиться. Наприклад:

Коли ми остаточно мігруємо db, нам доведеться змінити цю логіку

або

TODO: якнайшвидше, перегляньте перевірку вхідних даних - це може бути невдалим для X або Y типу введення, можуть знадобитися масштабні зміни, які зараз неможливо здійснити.

Для більш пізнього типу коментарів TODO повинна існувати інша форма документації, щоб переконатися, що такі зміни насправді відбуваються. Останнє, що вам потрібно, - це TODO, загублені у часі та просторі: P

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

Коментування стосується спілкування з людьми, тому, хоча послідовність є важливою, важливо не зациклюватися на принципах, коли самі принципи перешкоджають хорошому спілкуванню. При цьому я використовую такі псевдостандарти:

• Коментарі, що описують бажану поведінку, мають форму поданого часу напруженого імперативного речення.

  // Calculate the width of the curve at x height.
  

• Використовуйте набір ключових слів з усіма великими літерами, щоб описати загальні теми в кодуванні (і щоб спростити пошук):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>