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

[Serg V. Gulko]

Коллеги, хотелось бы узнать, как Вы оформляете документацию к своему коду на Perl.
Есть ли какие-нибудь более-менее общепринятые рекомендации по оформлению методов классов.
Мне бы хотелось указывать входные аргументы, выходные параметры и исключения, если метод их порождает.

Сергей

[Oleg Alistratov]

On 09.09.2011 17:12, Serg V. Gulko wrote:

> Коллеги, хотелось бы узнать, как Вы оформляете документацию к своему
> коду на Perl.
> Есть ли какие-нибудь более-менее общепринятые рекомендации по оформлению
> методов классов.

Пробовал NaturalDocs. Не слишком впечатлил.

Пробовал Doxygen, он покрасивей, но perl без плясок с бубном не умеет.

POD толком никто из них воспринять все равно не может.

Соответственно, выбрав конкретную систему документирования,
под нее комментарии и затачиваешь. Обычно у них есть какой-то птичий
язык, которым ты можешь уточнить смысл этого:

> Мне бы хотелось указывать входные аргументы, выходные параметры и
> исключения, если метод их порождает.

Что мне больше всего нравится в perl6 (кроме грамматик), так это
развесистые прототипы функций. Интерфейсы даже.

А пока perl6 не на конвейере, приходится как-то самому придумывать
какую-то формализацию описаний в дополнение к обычному PODу;
затем POD::Parser в руки и вперед.

--
Олег

[Dmitrii]

пїЅпїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ:
1) пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅ пїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ (пїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅ пїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ)
2) пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ!! пїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ :)

пїЅпїЅ пїЅпїЅпїЅпїЅпїЅ: пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ

--- пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ ---
пїЅпїЅ пїЅпїЅпїЅпїЅ: " Serg V. Gulko" <s.g...@gmail.com>
пїЅпїЅпїЅпїЅ: " Kiev Perl Users Group" <kiev-perl-...@googlegroups.com>
пїЅпїЅпїЅпїЅ: 9 пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ 2011, 17:12:58
пїЅпїЅпїЅпїЅ: Re: Best practice пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ

> пїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅ пїЅпїЅ Perl.
> пїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅ-пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ-пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ.
> пїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ.
>
> пїЅпїЅпїЅпїЅпїЅпїЅ

[Агнислав Онуфрийчук]

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

По теме вопроса: использовал POD. Хватало с головой.

9 сентября 2011 г. 18:39 пользователь Dmitrii <q7...@ukr.net> написал:

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

по этому: писать расписывать комментарии считают бессмысленным занятием



 --- Исходное сообщение ---
 От кого: " Serg V. Gulko" <s.g...@gmail.com>
 Кому: " Kiev Perl Users Group" <kiev-perl-...@googlegroups.com>
 Дата: 9 сентября 2011, 17:12:58
 Тема: Re: Best practice для оформления документации

[Serg V. Gulko]

Я тоже использую POD:) Вопрос лишь в подходе - есть ли более-менее устоявшийся стандарт для решения моих задач или каждый придумывает что-то свое?

В Птн, 09/09/2011 в 18:49 +0300, Агнислав Онуфрийчук пишет:

[Агнислав Онуфрийчук]

Я работал с конкретным продуктом (Request Tracker) и потому использовал стиль, принятый в нём. Там есть и input, и output.

9 сентября 2011 г. 18:54 пользователь Serg V. Gulko <s.g...@gmail.com> написал:

[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) = @_;
...
}

пїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅ пїЅпїЅпїЅ
пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ. пїЅпїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ-пїЅпїЅпїЅпїЅпїЅпїЅпїЅ,
пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ :)

пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅ, пїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ:

- пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ
- пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ
- пїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ
- пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ
- пїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ, пїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅ

--
пїЅпїЅпїЅпїЅ пїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅпїЅ

[Nab]

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

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

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

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

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

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

[Konstantin Cherednichenko]

В некоторых случаях гораздо проще ознакомится с ТЗ...

2011/9/12 Nab <n...@ukr.net>

--
Konstantin Cherednichenko
KC439-RIPE, KC96-UANIC

[Sergiy Borodych]

2011/9/12 Nab <n...@ukr.net>:

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

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