2-й или 3-й человек комментирует?

Просто столкнулся с этим, который должен быть здесь для полноты:

вычисляют PI в Piet

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

Здесь некоторое понимание самого языка

12
задан Emanuil Rusev 28 January 2010 в 03:19
поделиться

6 ответов

Я часто говорю в стиле врача:

// Now we take $x and check whether it's valid for this pass
21
ответ дан 2 December 2019 в 04:09
поделиться

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

// First, mumble the frabbitz.

blah blah

// Second, foobar the quux

blah blah

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

4
ответ дан 2 December 2019 в 04:09
поделиться

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

7
ответ дан 2 December 2019 в 04:09
поделиться

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

Обратите внимание, что комментарии хрупкие, и многие современные авторитетные источники (например, Clean Code) предлагают, чтобы функции и поля имели понятные имена. Но, конечно, есть много мест, где пояснительные комментарии все еще актуальны.

0
ответ дан 2 December 2019 в 04:09
поделиться

Иногда я говорю от 1-го лица, вот так

/*
Usage:  
set_position(0.5, 0.5);  // im in the center
set_position(0.0, 1.0);  // im in the lower,left corner
*/
1
ответ дан 2 December 2019 в 04:09
поделиться

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

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

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

3
ответ дан 2 December 2019 в 04:09
поделиться
Другие вопросы по тегам:

Похожие вопросы: