Лучшие Практики Написания Комментариев к Коду. Окончание
Начало
Продолжение 1
Продолжение 2
8. Добавляйте комментарии при исправлении ошибок
Комментарии следует добавлять не только при первоначальном написании кода, но и при его изменении, особенно при исправлении ошибок. Обратите внимание на этот комментарий:
/* ПРИМЕЧАНИЕ: как минимум, в Firefox 2, если пользователь уводит курсор за пределы окна браузера, событие перемещения мыши (и даже отпускания мыши) не будет получено, пока пользователь не перетащит курсор обратно в окно. Обойти проблему можно, реализовав onMouseLeave(). */Комментарий не только помогает читателю понять код в текущем и связанных методах, но и помогает определить, нужен ли ещё этот код и как его протестировать.
public void onMouseMove(Widget sender, int x, int y) { … }
Также может быть полезно сослаться на проблему в багтрекере:
// Имя используется в качестве заголовка,Если в системе контроля версий вы чётко следите за сообщениями коммитов, и добавляете в них ссылки на проблемы багтрекера,
// если свойство заголовка не задано (баг #1425).
git blame можно использовать для поиска коммита, в котором было изменение. Хотя здесь могут быть варианты. Если исправление состояло из нескольких коммитов или были более серьёзные изменения, вроде перемещения метода в другой класс или переименования/перемещения файлов, тогда поиск источника исправления может сильно усложниться.9. Используйте комментарии, чтобы отмечать незавершённые реализации
Иногда необходимо внести код в систему контроля версий, даже если он не завершён. Хотя может возникнуть соблазн не сообщать об известных недостатках в коде, лучше сделать их явными, например, с помощью комментария TODO:
/* TODO(hal): мы используем десятичный разделитель точку, вне зависимости от региона пользователя. Нам нужно подумать о том, как разрешить запятую в качестве десятичного разделителя, что потребует обновления синтаксического анализа чисел и других мест, где числа парсятся из строк, таких как FormatAsDecimal */Использование стандартного формата для таких комментариев помогает измерить и устранить технический долг. А ещё лучше добавить проблему в багтрекер и указать ссылку на неё в своём комментарии.
Итого
Я надеюсь, что приведённые выше примеры показали, что комментарии не извиняют и не исправляют плохой код; они дополняют хороший код, предоставляя информацию другого типа. Как писал соучредитель Stack Overflow Джефф Этвуд: «Код говорит вам, как, а комментарии говорят вам, почему».
Следование этим правилам поможет вам и вашим товарищам по команде сэкономить время и нервы. Тем не менее, я уверен, что эти правила не являются исчерпывающими, и с нетерпением жду ваших вариантов в комментариях.
Источник: https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/