Являются ли комментарии от первого лица отвлекающими и непрофессиональными?

Я просто обнаружил, что пишу следующий комментарий в некотором (архаичном Visual Basic 6.0) коде, который я писал:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Я не уверен, почему я подсознательно использую «мы» в моих комментариях. Я подозреваю, что это потому, что я представляю, что кто-то шагает по коду, как будто он на самом деле «выполняет» все команды в каждой строке, а не просто наблюдает, как они происходят. С таким мышлением я мог бы использовать I can resize it, так как я «делаю» это сейчас или you can resize it, как если бы я говорил с тем, кто «делает» это в будущем, но так как оба из этих случаев, скорее всего, случается, я использую «мы», как будто я веду кого-то еще через мой код.

Я могу просто переписать это it can be resizedи избежать этой проблемы, но это пробудило мое любопытство: часто ли используют в комментариях первое лицо, подобное этому, или это считается отвлекающим и / или непрофессиональным?

Комментарии должны быть написаны для понимания людьми. Когда люди общаются, мы обычно используем «я», «мы», «вы» и т. Д.

Когда кто-то пытается понять какой-то код, есть два или более действующих лиц: человек, читающий его, и первоначальный автор кода. Сказать «мы» - это хорошо. Если не сказать «профессионал», вы имеете в виду «роботоподобный».

Я бы посоветовал не использовать «Я», потому что он автоматически принимает на себя всю ответственность за код. Если другие люди читают это, это будет выглядеть плохо, потому что в этом случае это должно быть командным усилием. Я безразличен к использованию «мы». Это может, однако, столкнуться с включением других читателей не по-своему.

Мой голос все еще идет для краткости и краткости. Если сообщение может быть передано менее многословно, зачем выбирать что-то еще? Итак, что касается этого примера, я бы написал:

'The form is not minimized so it can be resized safely.

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

Объясняя такие вещи, как требования или обоснование, я говорю «мы», как у вас там:

// We can't proceed unless the user has given us this information.

Если я объясняю процесс, я склонен использовать императивный (командный) голос (поправьте меня, если это неправильный термин):

// Get the foo from bar and make sure it follows our required format.

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

Я думаю, что это просто вариант академического / технического стиля письма, который часто безличен. Используя пассивный голос, используя «королевское мы» («один» так устарел).

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

Тем не менее, я часто использую первое лицо в комментариях - чтобы объяснить, почему я принял конкретные решения, и о чем я думал.

Комментарии должны сказать вам, почему что-то делается, а не то, что делается. Если то, что делается, не очевидно из кода, исправьте код, а не просто добавьте комментарий. От первого лица, от второго лица и т. Д. Не имеет значения, важно ли передавать необходимую информацию.

Если вы должны рассказать код, предпочтите императивы, например,

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(И, пожалуйста, не используйте голые константы, такие как «1» в коде)

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

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

Пример:

(Вы / мы / должны) использовать делегата для передачи события изменения размера окна родителю

Делегат должен использоваться для передачи события изменения размера окна родителю.

Другой пример (обратите внимание, что вы часто можете опустить формы человека в комментариях):

(Мы) поймали исключение. (Мы будем), показывая диалоговое окно с ошибкой.

Возникла исключительная ситуация, и появится диалоговое окно с сообщением об ошибке.

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

Если вы говорите о выполнении программы, это не «мы», «вы» или «я». Антропоморфизм может быть настолько широко распространенным, что может быть незаметным, но это опасная привычка (Предупреждение PDF. Предупреждение Dijkstra.):

Я думаю, что антропоморфизм хуже всего. Теперь я видел программы «пытаться что-то делать», «хотеть что-то делать», «верить в то, что это правда», «знать вещи» и т. Д. Не будьте настолько наивными, чтобы полагать, что такое использование языка безвредно. Он предлагает программисту идентифицировать себя с выполнением программы и почти навязывает ему использование операционной семантики.

Я не думаю, что ни первое лицо, ни «королевское мы» кажутся непрофессиональными или отвлекающими. Я действительно думаю, что мы должны приложить усилия для написания англоязычных комментариев в E-Prime , подмножестве английского языка, в котором нет глагола «быть».

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

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Ну, может быть, не все сразу, но из-за равенства можно сделать комментарии неясными.

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

Правильный стиль комментирования - безличное третье лицо; « Форма не свернута, поэтому ее можно безопасно изменить ».

• Я наивна
• Ты груб.
• Мы слишком формальны (и королевские).

Каждое предложение может быть перефразировано таким образом (см. Выше), и это единственный профессиональный способ написания.

Это зависит от комментария.

Как правило, я пишу комментарии в порядке, предложенном «Рот коровы» . Я также всегда пишу комментарии, генерирующие документацию (Doxygen, JavaDoc) таким образом.

Однако многие часто пренебрегают использованием контроля версий, чтобы определить, кто написал / коснулся строк в исходных файлах. Бывают случаи, когда говорить «Я» уместно, особенно когда довольно легко отследить «Я» до человека, написавшего код. Если вы, как частное лицо, приняли решение, я рекомендую использовать «I» (наряду с контролем версий) для выявления и отслеживания решений в соответствии с кодом.

Мой старый добрый отец (Мхрип) спрашивал: «У тебя есть более важные вещи?»

Однако лично мне нравится «мы». И я также задаюсь вопросом, почему я пишу мы в восходящих документах, даже не код, учитывая, что я единственный сотрудник в моей компании.

Впрочем, я и я согласны, что таким образом мы чувствуем себя менее одинокими :)

Я единственный, кто пишет «мы» и думает «я и компьютер» (или «моя команда и компьютер»)? «Мы» собираемся обработать запрос, выданный нам извне, это означает, что «мы» должны прочитать запрос, открыть некоторые окна, выполнить некоторые вычисления, основываясь на «наших» бизнес-требованиях. Это также помогает видеть код как часть вашей стороны, а не врага :-)

Для коротких комментариев я иногда пишу от второго лица, как если бы я инструктировал кого-то другого, почти как сообщение, адресованное следующему разработчику, чтобы прочитать комментарий. Такие как

//You can get a session_id from SYSSession.getSessionID() if you need one

Более длинные комментарии (например, длинный заголовок функции или несколько строк описания алгоритма) Я стараюсь сохранять нейтральность: нет от первого лица, от второго лица или от третьего лица.

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

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

Таким образом, если большинство комментариев можно выразить в коде, это оставляет очень мало причин для комментариев

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

Как правило, я бы предложил использовать от первого лица, то есть I.

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

Лично я бы написал (в C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Или что-то в этом роде, поэтому комментарии не нужны.