Как лучше всего комментировать в обзоре кода?

Моя команда только начала использовать crucible / fisheye для запуска проверки кода всякий раз, когда кто-то из нас регистрирует что-либо. Нас всего трое, и каждому из нас предлагается просмотреть код и оставить комментарии там, где мы сочтем нужным.

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

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

Чтобы прояснить: это действительно хороший ресурс для того, что я хотел бы прокомментировать: субъективен ли анализ кода или количественно (количественно)? , но я ищу, как это прокомментировать.

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

Требуемые изменения. Это те изменения, в которых я отмечаю, что код не соответствует функциональным требованиям или не работает и должен быть исправлен перед отправкой в ​​производство. Я склонен быть очень простым в этих комментариях. Требования говорят ..., это не делает этого. В противном случае произойдет сбой, если отправленное значение равно нулю (особенно если вы знаете, что случай произойдет на основе данных, которые будут отправлены).

Затем есть комментарии «это работает, но здесь есть лучший способ сделать это». Вы должны быть более мягкими в этом и делать больше продаж. Я мог бы сказать, что я сделал бы это вместо этого, потому что это, вероятно, будет лучше работать (я вообще рассматриваю код SQL, где производительность очень важна). Я мог бы добавить некоторые подробности о том, почему это лучший выбор, точно так же, как и при ответе на вопрос о переполнении стека. Я мог бы указать, что не нужно менять это для этого конкретного кода, но рассмотреть изменение в будущем кодировании. В основном с этими типами комментариев я обучаю людей с меньшим опытом того, что может работать лучше.

Затем есть комментарии «это работает, но мы делаем так». Это, вероятно, также потребует изменений. Они будут включать комментарии о стандартах компании или архитектуре, которую мы ожидаем от них использовать. Я хотел бы сослаться на стандарт или документ архитектуры и сказать им, чтобы исправить в стандарте. Комментарий был бы простым, но нейтральным, поэтому он отсутствует и т. Д., Или имена переменных не соответствуют нашему стандарту именования или подобным вещам. Например, наша архитектура для пакетов служб SSIS требует, чтобы пакет использовал нашу базу данных метаданных для хранения конкретной информации о пакете, и требует особой регистрации. Пакет будет работать без этих вещей, но они необходимы по причинам компании (например, нам необходимо сообщить о степени успешности импорта или проанализировать типы ошибок, которые мы получаем).

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

Если код соответствует вашим стандартам кодирования, но вы бы поступили иначе, вы должны спросить себя, что они сделали неправильно.

Если это не так… это просто не то, как вы бы это сделали, и вы просто не можете оставить это, попробуйте просто спросить: «Почему вы сделали это так, а не так?» Затем вы получаете их, чтобы понять, почему они сделали это так, как они, не говоря: «Я бы сделал это так, и вы тоже должны ...»

Вы также можете узнать что-то в процессе.

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

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

• Это приведет к сбоям в работе frobnitz, когда fooble находится в пределах 5 грамм от фактора snorgatz.

• Установленное соглашение для этого заключается в вызове fazzatz () с недавно инициализированным Squidge. Сделайте это методом, чтобы оно всегда происходило одинаково и не дублировалось.

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

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

Будут разногласия, и у рецензента и рецензента это будут возможности отстаивать свои позиции. Если вы по-другому сверстники и попали в тупик, найдите кого-нибудь старшего, чтобы разорвать галстук.

Это зависит от того, какая проблема была замечена

• Отсутствует уведомление о копирайте - распространенная и скучная проблема, просто краткий комментарий с изложением проблемы и дальнейшие действия
• места, где я мог бы сделать это по-другому - обычно склонен задавать вопросы здесь, а не делать заявления, иногда ответы оправдывают первоначальное решение, а иногда нет, и тогда я могу обратиться к ним более подробно
• места, где есть явный дефект, например, переопределение «Равно», которое может переполнять стек - достигните красной ручкой - пометьте его как дефект и очень четко объясните, почему оно сломано - также проверьте другие подобные области, чтобы убедиться, что не было систематической проблемы.

Из моего опыта:

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

2. Приятного разговора. Цените хорошую часть кодирования. Скажите ему, что «это лучшее, что я видел», если вы видите некоторые хорошие части в коде.

3. Попросите его просмотреть ваш код и принять и согласиться с действительными пунктами и исправить его. Уважайте его комментарии в вашем коде, и он автоматически будет уважать ваши комментарии к обзору кода.
4. Работайте на уровне разработчика, если это не очень важно или не требуется больше времени для исправления проблем с проверкой кода. Не переходите к менеджерам для простых проблем, если условия отсутствуют.
5. Посмотрите с точки зрения «Изучение из другого кода» вместо того, чтобы указывать на ошибки в коде.
6. Во время сеансов обзора кода процитируйте прошлые ошибки, которые вы сделали, и то, как проверки кода помогли вам и избежали больших производственных проблем, потому что вам помог другой взгляд.
7. Быть скромным. Больше признательности и меньше комментариев к нему :) Вы узнаете много нового во время проверки кода, и он также с удовольствием примет ваши комментарии.