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

[Sergiy Borodych]

2011/9/12 Nab <nab at ukr.net>:
> 09.09.11 в 18:39 Dmitrii в своём письме писал(а):
>
>> есть два варианта:
>> 1) Опытный программиста прочитает сам код и все поймет без каких либо
>> комментариев (разве, что в очень редких случаев надо прокомментировать)
>> 2) Не опытный программиста НЕ прочитает, но ему комментарии НЕ помогут все
>> равно!! разве, что книгу Вы писать в комментариях :)
>>
>> по этому: писать расписывать комментарии считают бессмысленным занятием
>>
>>
>
> Я понимаю что программисты люди толковые, но при этом они далеко не во всех
> вопросах профи, и если пишете проект не просто чтоб писать, а для решения
> конкретных задач в какой нибудь предметной области, то без ее знания  будет
> "гляжу в книгу, вижу фигу", не зависимо от опытности программиста :)
>
> Для неопытных программистов это полезно хотя бы тем что видно как правильно
> писать тот или другой код, то есть в целях обучения. Иногда в чужом коде
> можно увидать много полезного. Познакомится с другим стилем, а не только с
> тем что показан в учебнике.
>
> Потому писать комменты нужны. Документировать каждую функцию не всегда
> целесообразно, если она короткая с красноречивым названием и параметры
> очевидны, но сложные вещи документировать обязательно.
>
>

Полностью согласен AKA +1 :)

-- 
Sergiy Borodych
http://bor.org.ua