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

Question

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

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

или

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

Answer 1

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

Answer 2

Я часто склонны говорить врачу стиль:

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

Answer 3

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

// First, mumble the frabbitz. 

blah blah 

// Second, foobar the quux 

blah blah 

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

Answer 4

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

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

Answer 5

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

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

Answer 6

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

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

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