Комментарии второго или третьего лица?

Ответ 1

Я часто склонен говорить о стиле доктора:

// Now we take $x and check whether it valid for this pass

Ответ 2

Определенно стиль третьего лица.

Ответ 3

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

// First, mumble the frabbitz.

blah blah

// Second, foobar the quux

blah blah

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

Ответ 4

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

Встроенные комментарии предназначены для чтения вами и другими разработчиками, которые пытаются понять детали реализации вашего кода. Пока они понятны и понятны, имеет значение, если стиль немного необычен, грамматика немного бедна или есть несколько орфографических ошибок. Люди, которые его читают, не должны заботиться о таких вещах.

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

Ответ 5

Я иногда говорю в 1-м лице, вроде этого

/*
Usage:  
set_position(0.5, 0.5);  // im in the center
set_position(0.0, 1.0);  // im in the lower,left corner
*/

Ответ 6

Это может зависеть от того, сколько людей редактирует код и с какой целью. В моем собственном коде (который, тем не менее, для общественного мнения) я могу свободно добавлять некоторые личные комментарии, возможно, используя "я". В общественном проекте комментарии должны быть нацелены на общий стиль, и "я" может быть неуместным.

Обратите внимание, что комментарии являются хрупкими, и многие современные авторитеты (например, "Чистый код" ) предполагают, что функции и поля должны содержать значимые имена. Но, конечно, есть много мест, где по-прежнему важны пояснительные комментарии.