Чи відволікаючі та непрофесійні коментарі від першої особи?

Щойно я виявив, що я пишу наступний коментар у якомусь (архаїчному 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 Warning. Dijkstra Warning.):

Я думаю, що антропоморфізм найгірший за всіх. Зараз я бачив програми, які "намагаються робити речі", "хочуть робити речі", "вірять у те, що вони правдиві", "знаючи речі" тощо. Не будьте наївні, щоб вважати, що використання мови є нешкідливим. Він пропонує програмісту ідентифікувати себе з виконанням програми і майже змушує його використовувати оперативну семантику.

Я не думаю, що ні перша людина, ні "королівські ми" не здаються непрофесійними, або відволікаючими. Я думаю, що ми повинні докласти зусиль, щоб написати коментарі на англійській мові в E-Prime , підмножині англійської мови, яка не володіє дієсловом "бути".

Якщо ви надмірно використовуєте "бути" у коментарях, ви отримуєте заплутані твердження на зразок:

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

Добре, можливо, не все відразу, але рівність може насправді зробити коментарі незрозумілими.

Я думаю, що вимоги до написання в E-Prime допомагають зробити ці вимоги зрозумілішими, оскільки письменник повинен вказати на актора разом із дією.

Правильний стиль коментування - безособовість третьої особи; " Форма не зведена до мінімуму, тому її можна безпечно змінити ".

• Я наївний.
• Ви - лукаві.
• Ми занадто формальні (і королівські).

Кожне речення можна перефразувати таким чином (див. Вище), і це єдиний професійний спосіб написання.

Це залежить від коментаря.

Як правило, я пишу коментарі таким чином, як пропонував The Mouth of Cow . Я також завжди пишу коментарі, що створюють документацію (Doxygen, JavaDoc) таким чином.

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

Мій старий добрий батько (мхріп) запитав би: "Хіба у вас немає важливіших речей, які потрібно турбувати?"

Однак особисто мені подобається "ми". І мені також цікаво, чому я записую нас у документи, що не передаються в потоці, навіть не в коді, вважаючи, що я єдиний працівник моєї компанії.

Однак я сам і я згоден, що таким чином ми відчуваємо себе менш самотніми :)

Я єдиний, хто пише "ми" і думає "я і комп'ютер" (або "моя команда і комп'ютер")? "Ми" будемо обробляти запит, який нам подав зовні, це означає, що "нам" потрібно прочитати запит, відкрити деякі вікна, зробити деякі розрахунки, виходячи з "наших" бізнес-вимог. Це також допомагає бачити код як частину вашої сторони, а не ворога :-)

Для коротких коментарів я іноді пишу від другої особи, ніби доручаю комусь іншому, майже як повідомлення, спрямоване наступному розробнику прочитати коментар. Як от

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

Більш довгі коментарі (наприклад, довгий заголовок функції або кілька рядків опису алгоритму) Я намагаюся зберігати нейтралітет, не від першої особи, другої особи чи третьої особи.

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

Добре названий метод, хоч і малий, перемагає коментар, тому що коментарі та код легко синхронізуватися.

Отже, якщо більшість коментарів можна висловити в коді, це залишає дуже мало причин для коментарів

• Якщо ваш коментар - це ваша думка, то почніть з "я"
• Якщо ви вважаєте, що ваш коментар має бути спільною думкою (наприклад, найкращою практикою), тоді почніть з "ми"
• Якщо ваш коментар спрямований на якийсь хитромудрий код, написаний напіввідчуттям, то прокрутіть коментар, перейдіть і пробийте їх колегою заплутаного коду, а потім зверніться до цього віч-на-віч із ними.

Як правило, я б запропонував використовувати першу особу, тобто I.

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

Особисто я написав би (на C #):

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

Або щось у цьому напрямку, тому коментарі не потребують.