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

41

Я пишу (надеюсь) полезные комментарии в кодовой (C ++) документации типа:

The reason we are doing this is...

Причина, по которой я использую «мы» вместо «я», заключается в том, что я много пишу в академической среде, где «мы» часто предпочитают.

Итак, вот вопрос. Есть ли веская причина отдавать предпочтение одному над другим при документировании кода:

  1. Используйте «Мы»: причина, по которой мы это делаем ...
  2. Используйте «Я»: причина, по которой я делаю это ...
  3. Используйте мое имя: причина [my name]сделала это ...
  4. Пассивный голос: причина, по которой это было сделано ...
  5. Ни: сделай это, потому что ...

Я выбрал # 1, потому что я привык писать таким образом, но документация не для автора, а для читателя, поэтому мне интересно, полезно ли добавить имя разработчика или просто добавить еще одну вещь, которая должна быть изменено при сохранении кода.

Алан Тьюринг
источник
Я думаю, что это зависит от личных предпочтений. Я не вижу причин, почему одно было бы более ясным, чем другое в целом.
ConditionRacer
6
Как насчет № 5: «Когда в ходе человеческих событий ...»;)
Wingwing
8
«Четыре очка и семь секунд назад наши предки узнали, что foo должен быть запрещен, по крайней мере, наши силы должны быть побеждены с помощью NULL»
Филипп
Сильно относится к английскому языку. SE: Почему программисты всегда используют «мы», когда на самом деле они означают «я» или «вы»? (Который был, к сожалению, закрыт)
Изката
2
Почему не говоришь This code was written like this because...? (Пассивный голос)
Элвин Вонг

Ответы:

77

Я бы пошел с:

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

Вместо того чтобы сказать «Причина, по которой это было сделано, заключается в том, что у каждого Foo должен быть столбец», просто скажите «У каждого Foo должен быть столбец». Сделайте комментарий в активном изложении причины, а не пассивном. В целом это лучший стиль написания, лучше соответствует характеру кода (который что- то делает ), и the reason this was doneфраза не добавляет никакой информации вообще. Это также позволяет избежать именно той проблемы, с которой вы столкнулись.

Bobson
источник
Не могли бы вы немного рассказать о том, почему вы это делаете? Без объяснения этот ответ выглядит скорее как голое мнение, несколько противоречащее руководящим принципам : «... Мнение не так уж и плохо, если оно подкреплено чем-то иным, чем« потому что я эксперт » или «потому что я так сказал», или «просто потому что». Используйте свой конкретный опыт, чтобы подкрепить свои мнения, как указано выше, или укажите на какое-либо исследование, которое вы провели в Интернете или где-либо еще, которое предоставляет доказательства в поддержку ваших утверждений ... »
gnat
15
@gnat «Причина, по которой это было сделано» ничего не добавляет к объяснению. Комментарии должны содержать достаточно текста, чтобы понять суть и не более. Оставьте тонкости, преамбулы и другие наполнители текста.
Дэвид Харкнесс
@gnat - я только что закончил добавлять больше, когда увидел твой комментарий.
Бобсон
1
Я думаю, что мой пример был слишком упрощенным, потому что действительно «причина, по которой это было сделано» ничего не добавляет. Но есть случаи, когда сложная ситуация требует некоторого объяснения, и в этом случае я нахожу более естественным использовать «мы» или «я», так же, как я использовал «я» несколько раз в этом комментарии. Но я думаю, что ваш ответ ясен по духу: «декларативный» предлагает: используйте наименьшее количество слов, которые ясно показывают смысл.
Алан Тьюринг
7
Я читаю //как becauseв большинстве случаев.
Ilmo Euro
23

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

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

Я бы сказал:

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

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

Карл Билефельдт
источник
4

В 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);
    ...
}
PSWG
источник
4
Примечание: SanitizeDataдолжен вернуть SafeComplexObject. ;)
Джон Пурди
Я согласен, но я предпочитаю буквальные (а не метафорические) комментарии, особенно если могут быть разработчики из разных языков.
Джон Б. Ламбе
2

Еще одна идея, которую следует рассмотреть, - это хорошо разработанный модульный тест, который демонстрирует, почему код работает так, как он работает вместо написания описательного комментария. Это имеет пару преимуществ по сравнению с написанием комментариев:

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

  2. Юнит-тесты дают сопровождающему простой способ играть с кодом. Изучение новой кодовой базы может быть намного проще, если у вас есть отдельные блоки, которые вы можете разбить, чтобы наблюдать за изменениями.

Несмотря на то, что этот путь требует дополнительной работы, модульное тестирование может быть отличной формой документации.

mortalapeman
источник
1

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

Я не хотел бы отговаривать кого-либо комментировать свой кодекс, потому что он обеспокоен регистром, временем и личностью своих местоимений.

Джон М Гант
источник
Позвольте мне уточнить: для комментариев, которые станут частью официальной документации, уместен более формальный тон, и лучше избегать «я» и «мы». С этим ответом я имел в виду случайные пояснительные комментарии, например, когда вы сделали что-то, что будет выглядеть неправильно для следующего парня. В тех случаях, когда его увидят только люди, работающие в одной и той же кодовой базе, я говорю, что делайте все, что наиболее четко передаст ваше значение, даже если оно I wrote the code this way because...или оно what we really need here is.... В этих случаях четкий комментарий важнее строгого стиля.
Джон М Гант
1

Причина, по которой я использую «мы» вместо «я», заключается в том, что я много пишу в академической среде, где «мы» часто предпочитают.

Это плохой стиль, даже для академических работ, если только вы не пытаетесь скрыть, кто на самом деле решил именно этот момент.

Что касается вашего конкретного вопроса: я бы не оставил такой комментарий, если он не начинается с:

// TODO: clean this up, ...

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

BЈовић
источник