Мне просто интересно, но если кто-то хочет сделать аргумент, что один лучше другого, иди за ним!
Это комментарии, например, только для написания стилей, не предназначенные для оценки их содержания!....
Комментарии первого лица "Я":
//i'm setting this to 1 because it breaks otherwise
Комментарии первого лица "мы":
//we need to set this to 1 - trust me
Второе лицо:
//you need to set this to 1 so it don't break
Третье лицо:
//this needs to be set to one
"Я", если это хак, я смущен.
"Мы", если я беру читателя через запутанный алгоритм.
"Вы", если я объясню, как использовать API.
//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
Здесь ссылка от Microsoft, она специально нацелена на стандарты кодирования/рекомендации при настройке платформы .NET. Но это может быть полезно.
http://msdn.microsoft.com/en-us/library/aa291593.aspx#vxconcodingtechniquesanchor2
И из вашего выбора 4 я предпочитаю использовать # 4.
Я использую третьего лица для всех комментариев.
Я смешиваю все три, если это необходимо, что может быть не лучшим образом при составлении прозы.
Я буду чередовать "I" и "мы" в зависимости от того, полностью ли это моя ошибка или решение комитета/экспертного совета.
В основном я использую императивный режим для однострочных ( "Вычислите foobar, применяя алгоритм barfoo", "Обратитесь к Foo и Bar 1967 для получения более подробной информации)," Мы "для более подробных объяснений, которые могут быть выдержками из технической статьи.
Пассивный третий человек более традиционен, но многие научные журналы предпочитают более активное "мы", так как оно более читаемо. Это также моя любимая форма, так что руководство, которое я использую в своей документации и комментариях.
Я предпочитаю пассивный голос или императив (последний только для коротких комментариев), за исключением случаев, когда я имею в виду конкретно (первое лицо единственное) (например, мнение или неофициальная информация, которую я получил, например, обращение к провайдеру плохо документированный API, или в примечании, документирующем мое исследование неисправного драйвера (объяснение обходного пути) или ссылки на мою корреспонденцию с сторонним поставщиком (со ссылкой на письмо в нашей вики)) или нашей организации (первое лицо множественное число ) (например, как наша компания использует программное обеспечение, реализована ссылка на корпоративную стратегию, которая влияет на что-то).
Мне всегда нравилось это руководство по стилю от Sun/Oracle, независимо от языка программирования: Как писать комментарии к Doc для инструмента Javadoc: руководство по стилю. Правила сохраняют формальность и последовательность, не становясь глупыми: я думаю, Оруэлл одобрит
Я буду использовать "я", если я объясню свое собственное решение использовать определенную логику или шаблон. Если это групповой проект, я обычно подпишу этот комментарий, чтобы люди могли напрямую обращаться к нам с вопросами.
В противном случае я буду использовать третьего человека.
Вы никогда не знаете, будет ли этот код использоваться для кого-то другого, вы можете продать код, вы можете опубликовать его под любой лицензией с открытым исходным кодом и т.д. Поэтому нехорошо видеть: "Я устанавливаю это.." или "Нам нужно установить это...", по крайней мере, "Пожалуйста, обновите следующие переменные:"
Я всегда использую третьего человека и вы делаете это, я всегда использую
/*********************************************
**
** last edited by Bruno Alexandre, 14.Oct.08
** log info:
** - 10.Oct.08 : Added send email when buggy
**
************************************************/
в верхней части каждой кодовой страницы (классы, CSS, Javascript и т.д.)
и используйте его код:
//проверить, есть ли у пользователя уже подписка на рассылку новостей
if (! mySubscription.Contains(myUser))...
Третье лицо, но, пожалуйста, включите объяснение. Не нужно быть длинным или исчерпывающим, просто зачем вы это делаете, что сломается, если оно изменится, что-то. Нет, я вам не доверяю, или я не верю, что текущее обстоятельство всегда потребует этого взлома. Связанная ошибка может быть исправлена сейчас, пять лет спустя. Или это может быть проще исправить.
Я либо деперсонализую свои комментарии, либо использую "мы". "Мы" в смысле ходьбы по алгоритму с читателем.
В основном пассивным голосом, что вообще важно, чем кто для меня.
//This must be set to one for configuration
// This is yet to be implemented
// still to be evaluated for edge cases
и др.