Я пишу (надеюсь) полезные комментарии в кодовой (C ++) документации типа:
The reason we are doing this is...
Причина, по которой я использую «мы» вместо «я», заключается в том, что я много пишу в академической среде, где «мы» часто предпочитают.
Итак, вот вопрос. Есть ли веская причина отдавать предпочтение одному над другим при документировании кода:
- Используйте «Мы»: причина, по которой мы это делаем ...
- Используйте «Я»: причина, по которой я делаю это ...
- Используйте мое имя: причина
[my name]
сделала это ... - Пассивный голос: причина, по которой это было сделано ...
- Ни: сделай это, потому что ...
Я выбрал # 1, потому что я привык писать таким образом, но документация не для автора, а для читателя, поэтому мне интересно, полезно ли добавить имя разработчика или просто добавить еще одну вещь, которая должна быть изменено при сохранении кода.
documentation
Алан Тьюринг
источник
источник
This code was written like this because...
? (Пассивный голос)Ответы:
Я бы пошел с:
# 6. Декларативный: ...
Вместо того чтобы сказать «Причина, по которой это было сделано, заключается в том, что у каждого Foo должен быть столбец», просто скажите «У каждого Foo должен быть столбец». Сделайте комментарий в активном изложении причины, а не пассивном. В целом это лучший стиль написания, лучше соответствует характеру кода (который что- то делает ), и
the reason this was done
фраза не добавляет никакой информации вообще. Это также позволяет избежать именно той проблемы, с которой вы столкнулись.источник
//
какbecause
в большинстве случаев.Я не предпочитаю ни того, ни другого, и на самом деле я бы вообще отбросил эту вступительную фразу и просто дошел до сути. Я также стараюсь избегать просто говорить «это», потому что не остается способа определить, синхронизирован ли комментарий с кодом. Другими словами, вместо:
Я бы сказал:
Тот факт, что вы добавляете комментарий, подразумевает, что вы указываете причину, поэтому вам не нужно излишне говорить людям, что вы объясняете причину. Просто укажите причину как можно точнее, чтобы они знали как можно яснее, как поддерживать этот код позже.
источник
В C # (и в большинстве инструментов документации на других языках) существует различие между документацией и встроенными комментариями. Мое личное мнение таково, что вы всегда должны использовать формальные, декларативные комментарии в стиле, как Бобсон и другие предлагают в документации класса или члена, но в коде нет ничего плохого в том, чтобы быть менее формальным. На самом деле, иногда неформальный комментарий более эффективен для объяснения причин чего-то, чем полная экспозиция на официальном английском языке.
Вот пример, который, я думаю, иллюстрирует суть.
источник
SanitizeData
должен вернутьSafeComplexObject
. ;)Еще одна идея, которую следует рассмотреть, - это хорошо разработанный модульный тест, который демонстрирует, почему код работает так, как он работает вместо написания описательного комментария. Это имеет пару преимуществ по сравнению с написанием комментариев:
Комментарии не всегда меняются при изменении кода, что в дальнейшем может привести к путанице.
Юнит-тесты дают сопровождающему простой способ играть с кодом. Изучение новой кодовой базы может быть намного проще, если у вас есть отдельные блоки, которые вы можете разбить, чтобы наблюдать за изменениями.
Несмотря на то, что этот путь требует дополнительной работы, модульное тестирование может быть отличной формой документации.
источник
Хорошие комментарии трудно написать, и даже самые лучшие комментарии часто трудно прочитать и понять. Если ваш комментарий достаточно лаконичен, чтобы я мог усвоить его, и достаточно точен, чтобы передать то, что мне нужно знать о коде, мне не имеет значения, какие местоимения вы используете.
Я не хотел бы отговаривать кого-либо комментировать свой кодекс, потому что он обеспокоен регистром, временем и личностью своих местоимений.
источник
I wrote the code this way because...
или оноwhat we really need here is...
. В этих случаях четкий комментарий важнее строгого стиля.Это плохой стиль, даже для академических работ, если только вы не пытаетесь скрыть, кто на самом деле решил именно этот момент.
Что касается вашего конкретного вопроса: я бы не оставил такой комментарий, если он не начинается с:
или если это не объясняет что-то очень важное, это может быть не так ясно из кода. В этом случае сделайте комментарий как можно более кратким.
источник