«Я», «Мы» или Ни в документации кода

Я пишу (надеюсь) полезные комментарии в кодовой (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, ...

или если это не объясняет что-то очень важное, это может быть не так ясно из кода. В этом случае сделайте комментарий как можно более кратким.