Просто столкнулся с этим, который должен быть здесь для полноты:
, Это имеет довольно хорошее свойство, что точность может быть улучшена, делая программу больше.
Здесь некоторое понимание самого языка
Я часто говорю в стиле врача:
// Now we take $x and check whether it's valid for this pass
Один полезный совет: постарайтесь, чтобы каждый комментарий был как можно более самодостаточным. Например, такая форма:
// First, mumble the frabbitz.
blah blah
// Second, foobar the quux
blah blah
это хорошее повествование, но затрудняет редактирование кода, потому что «Первая» и «Вторая» части могут стать некорректными. В конце концов, они не так много добавляют к комментариям, но делают их хрупкими взаимосвязанными.
Это может зависеть от того, сколько людей редактирует код и с какой целью. В моем собственном коде (который, тем не менее, доступен для всеобщего ознакомления) я могу свободно добавлять некоторые личные комментарии, возможно, используя «Я». В коммунальном проекте комментарии должны быть нацелены на общий стиль и «Я». может быть неуместным.
Обратите внимание, что комментарии хрупкие, и многие современные авторитетные источники (например, Clean Code) предлагают, чтобы функции и поля имели понятные имена. Но, конечно, есть много мест, где пояснительные комментарии все еще актуальны.
Иногда я говорю от 1-го лица, вот так
/*
Usage:
set_position(0.5, 0.5); // im in the center
set_position(0.0, 1.0); // im in the lower,left corner
*/
Я считаю, что вы должны просто использовать тот стиль, который вам удобнее всего.
Встроенные комментарии предназначены для чтения вами и другими разработчиками, пытающимися понять детали реализации вашего кода. Если они ясны и разборчивы, имеет значение, если их стиль немного необычен, грамматика немного плохая или есть несколько орфографических ошибок. Люди, которые его читают, не должны беспокоиться о подобных вещах.
Комментарии, которые извлекаются для формирования документации API, заслуживают большего внимания к тонкостям стиля, грамматики и орфографии. Но даже здесь точность и полнота гораздо важнее.