Каковы наиболее часто используемые рекомендации * для документирования кода Perl?
Вот пример из правил javadoc:
"Gets the label of this button. (preferred)" vs.
"This method gets the label of this button. (avoid) "
Я ничего не нашел в perlstyle или в Extreme Perl - стиль кодирования. Возможно, PBP?
* Чтобы не вызывать мнения, основанные на мнениях, которые привели бы к закрытию вопроса; ссылки, требуемые для частоты использования
Книга Дэмиена Конвей Perl Best Practices посвящена главе документации.
perldoc perlstyle дает некоторые быстрые рекомендации для документации по каналу (подробнее в perldoc perldoc) - всегда хорошо, когда модуль имеет собственную встроенную документацию POD.
Я верю, что perlcritic содержит некоторые предложения по документации (закрепите свой код с помощью Perl:: критик).
Существует хорошая запись о стандартах кодирования Perl по следующей ссылке, которая предоставит вам раздел "Стандарты документации".
Не знаю, нашли ли вы ответ на этот вопрос. Люди рассказывают вам о стиле кодирования Perl, но не документируют.
Если вы говорите о том, как вводить комментарии внутри своего кода, стандарт должен комментировать обзор вашего кода и то, что делает конкретный раздел, но не комментировать, какая конкретная строка кода делать:
# $foo += $bar #Adding Bar to Foo
Это не все, что полезно. Честно говоря, я просто счастлив видеть ЛЮБЫЕ комментарии, даже если они полностью неточны и устарели. Я видел так много кода Perl, который полностью лишен комментариев, стиля форматирования или даже логической когерентной структуры.
Теперь, если вы говорите о том, как комментировать вашу общую программу, например Javadoc, с Java, Perl имеет нечто, называемое "POD", которое позволяет вам документировать код. Не совсем так, как Джавадок. Javadoc фактически использует ваш функциональный параметр вызова в документации, которая довольно крутая, и POD этого не делает.
Сделайте a perldoc perlpod и perldoc perlpodspec из командной строки. В принципе, Perl POD - это текст с минимальным стилем, закодированным в нем. Самое главное помнить, что вы пустые строки между вашими различными элементами POD, или они не будут интерпретироваться.
POD может быть встроен в Perl-код, и интерпретатор Perl пропустит первую команду POD, пока не найдет =cut. Многие люди используют этот факт, чтобы помочь NOP вытащить целые патроны кода в Perl, не прибегая к созданию пучка # перед каждой строкой.
Некоторым людям нравится встраивать программу POD в нее, потому что она помещает документацию POD в область кода, где она используется. Это позволяет легко обновлять POD, и поскольку POD довольно легко сканировать глазами, люди могут использовать POD для фактического документирования, а не просто с помощью комментариев.
Другие предпочитают помещать весь POD в конце своей программы, возможно, после строки __END__. Некоторые более старые интерпретаторы Perl не могут читать POD (но если вы используете интерпретатор Perl, который был старым, вы должны действительно обновить свою установку на Perl). Другие, не нравится, как встроенный POD разрывает код, который, по их мнению, затрудняет чтение. Я просто взволнован, чтобы увидеть какую-либо документацию в программе Perl.
Чтобы увидеть документацию POD, вам нужно только ввести perldoc <progName> из командной строки. Вы можете также использовать различные команды POD, такие как pod2text, pod2man и pod2html для создания документации в различных форматах. Также существует команда podchecker, которая проверит синтаксис вашего POD для ошибок.
Try http://perldoc.perl.org/perlmodstyle.html и документы perlmodstyle.