>Именно что функция делает и какие косяки могут быть должны демонстрировать юнит тесты
Да. Но они описывают внешнее, а предназначение функции (обязательно всегда) и особенности внутренних потрохов (иногда надо) они не раскрывают. А актуальность комментариев можно поддерживать переодической инспекцией кода.