"Я", "Ми" або Ні в кодовій документації

Я вважаю, що пишу (сподіваюсь) корисні коментарі в кодовій (C ++) документації такого типу:

The reason we are doing this is...

Причина, що я використовую "ми" замість "я", полягає в тому, що я багато навчаюсь писати там, де "ми" часто віддають перевагу.

Тож ось питання. Чи є вагомі причини віддати перевагу одному над іншим у документування коду:

1. Використовуйте "Ми": Причина, по якій ми це робимо, це ...
2. Використовуйте "Я": Причиною цього я є ...
3. Використовуйте моє ім'я: Причина [my name]цього ...
4. Пасивний голос: Причиною цього було ...
5. Ні: Робіть це тому, що ...

Я вибираю №1, тому що я звикла писати саме так, але документація не для письменника, це для читача, тому мені цікаво, чи додати ім’я розробника корисно чи це просто додасть ще одну річ, яку потрібно бути зміненим при підтримці коду.

Я б пішов з:

№6. Декларативний: ...

Замість того, щоб сказати "Причиною цього було те, що кожен Foo повинен мати смугу", просто скажіть "У кожного Foo повинен бути бар". Складіть коментар до активної констатації причини, а не до пасивної. Це загалом кращий стиль письма в цілому, краще відповідає характеру коду (який щось робить ), а the reason this was doneфраза не додає жодної інформації. Це також уникає саме тієї проблеми, з якою ви стикаєтесь.

Я не віддаю перевагу жодному, і фактично я б зовсім не відмовився від цієї вступної фрази і просто дійшов до суті. Я також намагаюся уникати того, щоб просто сказати "це", тому що це не дає можливості сказати, чи коментар синхронізований з кодом. Іншими словами, замість:

// The reason this was done is to prevent null pointer exceptions later on.

Я б сказав:

// Frobnicate the widget first so foo can never be null.

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

У C # (і в більшості інструментів документації іншими мовами) існує різниця між документацією та вбудованими коментарями. Моя особиста думка полягає в тому, що ви завжди повинні використовувати офіційні коментарі в стилі декларацій, як пропонують Бобсон та інші в документації класу або члена, але всередині коду немає нічого поганого в тому, щоб бути менш формальним. Насправді, іноді неофіційний коментар є більш ефективним для пояснення того, чому щось робиться, ніж повний виклад у формальній англійській мові.

Ось зразок, який, на мою думку, ілюструє суть.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

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

1. Коментарі не завжди змінюються при зміні коду, що може призвести до плутанини згодом.

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

Незважаючи на те, що ця алея вимагає більшої роботи наперед, тестування блоку може бути відмінною формою документації.

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

Мені б не хотілося перешкоджати комусь коментувати свій код, оскільки вони стурбовані справою, часом та особою своїх займенників.

Причина, що я використовую "ми" замість "я", полягає в тому, що я багато навчаюсь писати там, де "ми" часто віддають перевагу.

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

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

// TODO: clean this up, ...

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