Чи хороша ідея огляду коду, який використовує лише коментарі до коду?

Передумови

• Команда використовує DVCS
• IDE підтримує аналіз коментарів (наприклад, TODO тощо)
• Такі засоби, як CodeCollaborator, коштують дорого за бюджет
• Такі інструменти, як герріт, занадто складні для встановлення або не використовуються

Робочий процес

• Автор публікує десь у центральній філії репо-функції
• Рецензент забирає його та починає огляд

• У разі виникнення запитань / проблем рецензент створити коментар зі спеціальною етикеткою, наприклад "REV". Така етикетка НЕ ​​МОЖЕ бути у виробничому коді - лише на етапі огляду:

  $somevar = 123;
  // REV Why do echo this here?
  echo $somevar;
  

• Коли рецензент закінчує публікувати коментарі - він просто вводить дурне повідомлення "коментарі" і відштовхується

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

Підтримка IDE

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

Запитання

1. Як ви вважаєте, ця методологія є життєздатною?
2. Чи знаєте ви щось подібне?
3. Що в ньому можна покращити?

Ідея насправді дуже приємна. На відміну від звичайних робочих процесів, ви зберігаєте огляд безпосередньо в коді, тому технічно вам не потрібно нічого, крім редактора тексту, щоб використовувати цей робочий процес. Підтримка в IDE теж приємна, особливо можливість відображення списку відгуків внизу.

Є ще кілька недоліків:

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

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

  Уявіть таку ситуацію. Аліса вперше переглядає код Еріка. Вона зауважує, що Ерік, молодий розробник, використовував синтаксис, який не є найбільш описовим у мові програмування, яка насправді використовується.

  Аліса пропонує альтернативний синтаксис і передає код назад Еріку. Він переписує код, використовуючи цей альтернативний синтаксис, який, на його думку, розуміє правильно, і видаляє відповідний // BLAкоментар.

  На наступному тижні вона отримує код для другого огляду. Чи змогла б вона насправді згадати, що вона зробила це зауваження під час першого огляду, щоб побачити, як Ерік вирішив це?

  Під час більш офіційного огляду Аліса могла відразу побачити, що вона зробила зауваження, і побачила різницю відповідного коду, щоб помітити, що Ерік неправильно зрозумів синтаксис, про який вона йому розповіла.

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

  Звичайно, така ж проблема існує і з будь-яким іншим коментарем; Наприклад, у виробництві є багато коментарів TODO (включаючи найкорисніший: "TODO: Прокоментуйте код нижче"), і багато коментарів, які не оновлювалися, коли був відповідний код.

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

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

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

• Ви також можете зіткнутися з незначними проблемами з синтаксисом (який також існує для коментарів TODO). Наприклад, що робити, якщо довгий коментар "// BLA" породжує кілька рядків, і хтось вирішить записати це так:

  // BLA This is a very long comment which is way beyond 80 characters, so it actually
  // fills more then one line. Since the next lines start with slashes, but not "BLA"
  // keyword, the IDE may not be able to show those lines, and display only the first one.
  

• І нарешті, як незначна і дуже особиста примітка: не вибирайте "BLA" як ключове слово. Це звучить некрасиво. ;)

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

• компактність. Якщо людині не вдається перевірити, чи вказаний вказівник не є нульовим (або якась інша поширена помилка початківця на мові, яку ви використовуєте), рецензент може залишити десятки коментарів REV для цього, і в документі можна сказати " Я знайшов 37 місць, де вказівники не перевірялися спочатку ", не перераховуючи їх усіх
• місце для похвал. Цей коментар, як REV this is a nice designвидається, виглядає незвично, але мої відгуки на коди часто включають схвалення та виправлення
• інтерактивність. Ваш зразок коментаря "чому ти це зробив?" і це дуже типовий. Підхід лише для коментарів не підтримує розмову. Людина може змінити свій код і видалити коментар або видалити коментар. Але "чому ти це зробив?" і "будь ласка, змініть це, це неправильно" - це не одне і те ж.
• ведення обліку. Пізніше рецензент може перевірити, чи дійсно був змінений код чи коментарі були просто видалені. Вони також можуть перевірити, що коментарі були "взяті на борт" і розробник більше не робить тих самих помилок при наступному огляді.

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

Інші говорили про обмеження такого підходу. Ви згадали, що такі інструменти, як герріт, було важко встановити - я пропоную вам поглянути на Фабрикатор (http://www.phabricator.com). Це система перегляду коду, яку Facebook використовує роками, і нещодавно була відкрита. Встановити це не важко, має відмінні робочі процеси та вирішує всі проблеми, згадані в інших коментарях.