не помещало мне завести тред, надеясь привлечь внимание к недокументированности.
Есть мнение, такие ключевые моменты нужно описывать не в комментариях, а в самой документации.
Обычно комментарии пишу, но печально смотреть, что они висят годами. Неплохо бы, чтобы комментарии со временем становились частью документации, иначе полезные сведения оказываются сильно рассредоточены.