Comments 2
Когда я пишу, скажем, недодрайвер для контроллера USB, я временами добавляю комментарии в стиле "что": но они, естественно, описывают не самоочевидные действия, а назначение этих действий применительно к конкретной железяке. Скажем, я пишу, что вот здесь я обрабатываю прерывание по поступлению пакета SETUP, здесь -- по завершению передачи данных и т.д. Хотя, казалось бы, причина прерывания понятна из флага в регистре состояния, который при этом анализируется, и такой комментарий не нужен, я давно уже убедился, что, возвращаясь к собственному коду спустя, скажем, полгода, я уже не помню назначение тех или иных битов регистров контроллера, и мне куда проще понять, что делается, глянув на краткий комментарий, чем открывать даташит в поисках описания нужных битов или же анализировать дальнейший код, чтоб уже из него догадаться, а что здесь происходит. Кроме того, такие комментарии позволяют структурировать код в рамках одной функции (обработчика прерываний, например), визуально отсекая одну часть от другой.
Ну и, конечно, я пишу комментарии в случае отнюдь не очевидных или "лишних" действий -- например, связанных с обходом аппаратных ошибок.
60 антипаттернов для С++ программиста, часть 11 (совет 51 — 55)