Уж лучше блоксхему рисовать чем зкмусоривать код комментариями.
Представь ситуацию ты сидел сидел с кодом и взял его изменил.
Коментарий теперь лжет (у макконела тоже было по этому поводу).
Самое лучшее документирование кода это назвать понятным образом переменные и методы, чтобы код читался как пьеса.акт 1. Название акта, действующие лица, характеры лиц, далее события/диалоги...
А все это комментарии это несовершенство.
Никогда не любил комментарии.
Он нужен если там какая хрень которую логически не объяснишь (ну и такое бывает)
А во всех остальных случаях - правильное именование.