я недавно открыл для себя (на самом деле читал это у кого-то, но
потом успешно забыл), что даже подробнейший комментарий (которыми я
снабжаю свои исходники) - абсолютно (ну почти) бесполезен, если
просто повторяет и описывает конкретные действия операторов в
строчке. Нужен именно функциональный комментарий, "что это такое и зачем делается, и где используется, и где это
важно" Отчасти эту функцию несут блочные комментарии (в дополнение к
строчным) т.е. в камментах не надо повторять на естественном языке то, что уже написано языком программирования (несмотря на расхожее ошибочное мнение, что "лучший комментарий к незнакомому языку программирования - комментария на знакомом языке программирования" :))
Нужно комментировать именно функционально что делается, к примеру:
бесполезный каммент:
S_CLR S_CMDuffer ;обнуляем первый байт командного буфера
(я и так вижу, что обнуляем байт :))
годный каммент:
S_CLR S_CMDuffer ;Очищаем байт команды в командном буфере, чтобы интерпретатор
; команд (CP) видел, что буфер пуст и ничего выполнять не нужно
Ну да, написание внятных камментов занимает время (как минимум половину времени программирования), но оно того стоит.