Насчет сферических комментариев в вакууме: Это холивар (Вадик не комментируй, ну пожалста). Есть несколько подходов и т.д. Напишу только один из самых холиварных тезисов: Черезмерная документация вредна. И в 95% случаев код может оставаться недокументированным (да и сами функции - тоже, если они названы нормально). Смысл в том, что вы читаете код чаще чем пишете и читаете именно код, а не комментарии. Комментарии полезны только в случае если встречается что-то сложное или редко используемое. А дальше все просто... Количество комментариев зависит от качества ваших программистов. Чем больше комментариев тем хуже качество программистов (бывают исключения, конечно).