Какой стиль письма вы используете при комментировании кода?

Ответ 1

"Я", если это хак, я смущен.

"Мы", если я беру читателя через запутанный алгоритм.

"Вы", если я объясню, как использовать API.

Ответ 2

//use imperative mode, few person/reader references if any
//comments generally annotate the code, rarely talk to the reader
//there is no reason to talk to the reader
//this is not a primer or a tutorial
//just record the information
//state the context
//note the exceptional cases
//justify the choices
//list just the facts
//save the prose for poetry and sci-fi
//some code is sci-fi, but hopefully not this

Ответ 3

Здесь ссылка от Microsoft, она специально нацелена на стандарты кодирования/рекомендации при настройке платформы .NET. Но это может быть полезно.

http://msdn.microsoft.com/en-us/library/aa291593.aspx#vxconcodingtechniquesanchor2

И из вашего выбора 4 я предпочитаю использовать # 4.

Ответ 4

Я использую третьего лица для всех комментариев.

Ответ 5

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

Ответ 6

Я буду чередовать "I" и "мы" в зависимости от того, полностью ли это моя ошибка или решение комитета/экспертного совета.

Ответ 7

В основном я использую императивный режим для однострочных ( "Вычислите foobar, применяя алгоритм barfoo", "Обратитесь к Foo и Bar 1967 для получения более подробной информации)," Мы "для более подробных объяснений, которые могут быть выдержками из технической статьи.

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

Ответ 8

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

Ответ 9

Мне всегда нравилось это руководство по стилю от Sun/Oracle, независимо от языка программирования: Как писать комментарии к Doc для инструмента Javadoc: руководство по стилю. Правила сохраняют формальность и последовательность, не становясь глупыми: я думаю, Оруэлл одобрит

Ответ 10

Я буду использовать "я", если я объясню свое собственное решение использовать определенную логику или шаблон. Если это групповой проект, я обычно подпишу этот комментарий, чтобы люди могли напрямую обращаться к нам с вопросами.

В противном случае я буду использовать третьего человека.

Ответ 11

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

Я всегда использую третьего человека и вы делаете это, я всегда использую

/*********************************************
**
** last edited by Bruno Alexandre, 14.Oct.08
** log info:
**  - 10.Oct.08 : Added send email when buggy
**
************************************************/

в верхней части каждой кодовой страницы (классы, CSS, Javascript и т.д.)

и используйте его код:

//проверить, есть ли у пользователя уже подписка на рассылку новостей

if (! mySubscription.Contains(myUser))...

Ответ 12

Третье лицо, но, пожалуйста, включите объяснение. Не нужно быть длинным или исчерпывающим, просто зачем вы это делаете, что сломается, если оно изменится, что-то. Нет, я вам не доверяю, или я не верю, что текущее обстоятельство всегда потребует этого взлома. Связанная ошибка может быть исправлена ​​сейчас, пять лет спустя. Или это может быть проще исправить.

Ответ 13

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

Ответ 14

В основном пассивным голосом, что вообще важно, чем кто для меня.

//This must be set to one for configuration
// This is yet to be implemented
// still to be evaluated for edge cases

и др.