Best practice для оформления документации

[Nab]

09.09.11 в 18:39 Dmitrii в своём письме писал(а):

> есть два варианта:
> 1) Опытный программиста прочитает сам код и все поймет без каких либо  
> комментариев (разве, что в очень редких случаев надо прокомментировать)
> 2) Не опытный программиста НЕ прочитает, но ему комментарии НЕ помогут  
> все равно!! разве, что книгу Вы писать в комментариях :)
>
> по этому: писать расписывать комментарии считают бессмысленным занятием
>
>

Я понимаю что программисты люди толковые, но при этом они далеко не во  
всех вопросах профи, и если пишете проект не просто чтоб писать, а для  
решения конкретных задач в какой нибудь предметной области, то без ее  
знания  будет "гляжу в книгу, вижу фигу", не зависимо от опытности  
программиста :)

Для неопытных программистов это полезно хотя бы тем что видно как  
правильно писать тот или другой код, то есть в целях обучения. Иногда в  
чужом коде можно увидать много полезного. Познакомится с другим стилем, а  
не только с тем что показан в учебнике.

Потому писать комменты нужны. Документировать каждую функцию не всегда  
целесообразно, если она короткая с красноречивым названием и параметры  
очевидны, но сложные вещи документировать обязательно.



-- 
С Уважением, Николай aka Nab.