madkoder.com

Комментировать код нужно и важно, это обязательно надо делать. Особенно какие-то нетривиальные моменты в коде, которые трудно понять с ходу. Но общая документация в больших проектах зачастую устаревает, её почти невозможно поддерживать в 100% актуальном состоянии. Поэтому некоторые вот товарищи раздули целый флейм на тему "лучшая документация это сам код" и даже книжку на эту тему посоветовали.

По мне так правило должно быть такое: свой код тщательно комментируй и по возможности поддерживай документацию, но с чужим будь готов к полному отсутствию оной. Зачастую наиболее "талантливые" и "творческие" личности на такие детали полностью забивают, так что иногда приходится разбирать всё с нуля...