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