Комментарии 2-го или 3-го лица?

Question

Вы пишете комментарии от 2-го или 3-го лица?

// go somewhere and do something (2nd person comment)

или

// goes somewhere and does something (3rd person comment) 

Answer 1

Я часто говорю по-докторски:

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

Answer 2

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

Answer 3

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

// First, mumble the frabbitz.

blah blah

// Second, foobar the quux

blah blah

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

Answer 4

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

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

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

Answer 5

Я иногда говорю от первого лица, вот так

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

Answer 6

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

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