Best practice для оформления документации
Oleg Alistratov
ali at ali.org.ua
Fri Sep 9 09:42:33 PDT 2011
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) = @_;
...
}
К каждой функции, как минимум, нужно написать, что она
принимает и возвращает. Ну разве что это синус-косинус,
тогда понятно :)
Кроме того, я обязательно описываю:
- пакет целиком
- константы
- весь экспорт
- публичные методы отделяю от «приватных»
- все исключительные ситуации, которые может выбросить функция
--
Олег Алистратов
More information about the Kiev-pm
mailing list