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