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

[Oleg Alistratov]

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


Ну не. Нельзя так легкомысленно обходиться с языком с вариантным типом
данных, где мы можем с легкостью принять в функцию ничего, или список,
или хэш, или хэшреф с преобразованием к объекту, или блесованную
ссылку нужного типа и все это по-разному обработать…

# Returns random real value:
#   without arguments - returns value in [0, 1)
#   with 1 argument   - returns value in [0, A)
#   with 2 arguments  - returns value in [A, B).
# Swaps the args if the first one is larger than second one.
#
sub rand_real(;$$)
{
     my ($self, $from, $to) = @_;
     ...
}

К каждой функции, как минимум, нужно написать, что она
принимает и возвращает. Ну разве что это синус-косинус,
тогда понятно :)

Кроме того, я обязательно описываю:

  - пакет целиком
  - константы
  - весь экспорт
  - публичные методы отделяю от «приватных»
  - все исключительные ситуации, которые может выбросить функция



--
Олег Алистратов