Стиль комментария: императив или третье лицо

Question

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

object.doSomething();

Мой подход к комментированию этой строки состоял бы в том, чтобы поместить комментарий позади него, используя третье лицо, как это было бы обычное английское предложение, содержащее строку в качестве темы:

object.doSomething(); // does (referencing to the line of code) some action

Но поскольку мы находимся на императивном языке и, таким образом, фактически «командуем» компьютером, можно даже подумать о том, чтобы поместить комментарий перед кодом и использовать императив:

//Do some action:
object.doSomething();

Это даже полезно, когда нужно прокомментировать несколько строк, связанных друг с другом.

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

Answer 1

Официальное руководство по стилю Oracle гласит:

Используйте 3-е лицо (описательное), а не 2-е лицо (предписательное).Описание написано от 3-го лица, а не от 2-го лица.

Получает метку.(предпочтительно)

Получить этикетку.(избегайте)

Руководство по стилю Oracle можно найти здесь .

Answer 2

Первый подход, безусловно, является более подходящим методом комментирования, так как это будут люди, читающие ваши комментарии, важно, чтобы их было как можно проще читать.//Do something звучит так, будто вы разговариваете с компьютером, а не объясняете, что делает код.

Answer 3

Для Python PEP-257 сообщает о строках документов (выделение добавлено):

Строка документа - это фраза, заканчивающаяся точкой. Он предписывает функцию или эффект метода как команда («Сделай это», «Верни это»), не как описание ; например не пишите "Возвращает путь ...".

И PEP257: Хорошая строка документации Python на примере еще более явная (выделение добавлено):

Обратите внимание, что все строки документации начинаются с однострочного резюме. Резюме написано в императивном настроении («делать», «использовать», «найти», «вернуться», «сделать», и т. д.) и заканчивается точкой.