Який найкращий спосіб коментувати огляд коду?

Моя команда щойно почала використовувати тигель / риб'яче око для ініціювання перегляду коду кожного разу, коли хтось із нас щось перевіряє. Нас лише 3, і нам рекомендується переглянути код та залишити коментарі, де ми вважаємо за потрібне.

Моє запитання: як мені найкраще залишити коментар до рядка коду, з яким я бачу проблему? Я хочу передати свою точку зору, не здаючись абразивною.

Мені не хочеться здаватися, що я на високому коні і кажу: " Я робив це так ... і я також не хочу здаватися, що намагаюся бути авторитетним і говорити щось на зразок " Це слід зробити так ... ", але мені все одно потрібно зрозуміти, що те, що вони роблять, не дуже добре.

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

Я схильний коментувати декілька загальних сфер, і кожен тип може бути по-різному.

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

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

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

Єдине, що ви не хочете робити в коментарях з перегляду коду - це особисто атакувати когось. Це також може допомогти, якщо ти знайдеш щось, що вони зробили добре, і зазначиш, що це було добре. Іноді я дізнаюся щось нове з огляду коду, і якщо б це зробити, я сказав це людині.

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

Якщо це не так, це просто не так, як ви це зробили, і ви просто не можете його залишити, спробуйте просто запитати "Чому ви зробили це саме так, а не так?" Тоді ви отримуєте їх, щоб визначити, чому вони зробили так, як вони це зробили, не кажучи: "Я зробив би це так, і ви також повинні ..."

Ви також можете щось дізнатися в процесі.

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

Не плутайте лаконічність з абразивністю. Коли щось є проблемою, документуйте це таким чином, що той, хто збирається це виправити, може зрозуміти. Дотримуйтесь фактів і не пишіть есе. А саме:

• Це призведе до несправності функціонування frobnitz, коли піни перебувають у межах 5 гримлів від коефіцієнта сноргаз.

• Створена умова для цього полягає у виклику fazzatz () зі свіжоініціалізованим Squidge. Зробіть це методом, щоб він завжди відбувався однаково і не дублювався.

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

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

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

Це залежить від того, яку проблему помітили

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

З мого досвіду:

1. Завжди мати при собі автора коду, переглядаючи його код. Переважно код проектується на дошці, і ви обидва можете добре бачити код.

2. Ведіть дружню розмову. Оцініть хорошу частину кодування. Скажіть йому, що "це найкраще, що я бачив", якщо ви побачите якісь хороші частини в коді.

3. Попросіть його переглянути ваш код і прийняти та погодитися на дійсні пункти та виправити його. Поважайте його коментарі у вашому коді, і він автоматично поважатиме ваші коментарі з перегляду коду.
4. Попрацюйте на рівні розробника, якщо це не дуже важливо або потрібно більше часу для виправлення проблем з переглядом коду. Не переходьте до менеджерів за простими, якщо відсутні умови.
5. Дивіться з точки зору "Навчання з іншого коду", а не вказуючи на помилки в коді.
6. Під час сеансів перегляду коду цитуйте минулі помилки, які ви допустили, і як огляди коду допомогли вам, і уникли великих проблем із виробництвом, тому що вам допомогла інша група очей.
7. Будь покірним. Більше вдячності та менше коментарів до нього :) Ви дізнаєтесь багато нового під час перегляду коду, а також він із задоволенням прийме ваші коментарі.