|
Размер: 2183
Комментарий:
|
Размер: 2344
Комментарий:
|
| Удаления помечены так. | Добавления помечены так. |
| Строка 28: | Строка 28: |
| === Аннотирование === [[py3tut:ontrolflow.html#function-annotations]] https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep526 |
|
| Строка 31: | Строка 38: |
| https://wiki.python.org/moin/DocumentationTools#Automatic_Python_API_documentation_generation_tools |
|
| Строка 32: | Строка 41: |
| * Промежуточное: [[http://epy3doc.sourceforge.net/|epy3doc]], [[http://docutils.sourceforge.net/|Docutils]], [[http://epy3doc.sourceforge.net/relatedprojects.html|всякое]] * «Традиционный» подход: [[http://www.stack.nl/~dimitri/doxygen/index.html|doxygen]] (+[[http://code.foosel.org/doxypy|doxypy]]) |
* пример * [[http://www.doxygen.nl/manual/docblocks.html#pythonblocks|Doxygen]] ([[https://engtech.wordpress.com/2007/03/20/automatic_documentation_python_doxygen/|пример]]) . /!\ Устарело? |
| Строка 35: | Строка 45: |
| * [[http://www.mkdocs.org/|MkDocs]] | * [[http://www.mkdocs.org/|MkDocs]] сайт-генератор |
Стиль программирования, комментарии и документирование
Оформление кода
Основная ссылка: pep-0008 — рекомендации к оформлению кода.
Анализаторы кода:
Статический анализ: pyflakes, …
PyLint
Жёсткость pep-0008
Пример: в коде PyGame-проекта
- Настройка:
pylint --generate-rcfile
- Отдельные параметры
- Пример настройки для vim
Почему так делать не всегда надо
Комментарии
- Не «что» и «как», а «зачем» и «почему»
- Комментарии vs. код на Python (это не Си же)
- Комментарии vs. строки документации
Выковыривание комментариев с помощью inspect.getcomments()
Аннотирование
https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep526
Документирование
Битва PEP-ов: pep-0256, pep-0258 — оба отвергнуты.
https://wiki.python.org/moin/DocumentationTools#Automatic_Python_API_documentation_generation_tools
- пример
![/!\](/moin_static197/modernized/img/alert.png "/!\")
Устарело?
MkDocs сайт-генератор