Когда я работал C++-разработчиком в CQG у нас было забавное правило, которым пользуюсь до сих пор. В новом коде было необходимо документировать только классы и функции (а их нужно было документировать всегда, для большой кодовой базы это необходимо), но сам код практически не документировался. Потому-что новый код всегда чистенький, гладенький и в целом понятный. Но когда идет вставка кода в уже существующий метод, хорошим тоном было описать кто и зачем этот фрагмент вставил.

int some() {
  // ... много кода 

  // av: fix of #342987. Иногда внешний сервис возвращает 1, но при этом ...
  if (...) {
    // ...
  }

  // ... еще много кода
}

Формально эту информацию можно достать с помощью git blame (ну не git на самом деле, гита тогда еще не было), однако тогда приходится делать много лишних кликов, прыгать по истории и вникать во все комиты, в которых менялся данный файл. Фактически же такие комменарии очень сильно помогают разобраться в конкретном файле. И чем больше рубцов, тем более легаси код.