Различия между версиями 1 и 6 (по 5 версиям)
⇤ ← Версия 1 от 2019-04-11 14:49:42 →
Размер: 2202
Редактор: FrBrGeorge
Комментарий:
← Версия 6 от 2019-04-12 15:26:58 → ⇥
Размер: 2826
Редактор: FrBrGeorge
Комментарий:
Удаления помечены так. Добавления помечены так.
Строка 3: Строка 3:
-----
'''TODO'''
Строка 12: Строка 10:
 * Статический анализ: [[pypi:pyflakes]], …

=== PyLint ===		  * Статический анализ: [[pypi:pyflakes]]/[[https://flake8.readthedocs.io/en/latest/|flake8]], …
Строка 16: Строка 12:
  * Пример: [[https://github.com/FrBrGeorge/PyGame/tree/9899d89a53f7ff840a4c80edcb5561f7f3646013|в коде PyGame-проекта]]
 * Настройка:
  * `pylint --generate-rcfile`
  * Отдельные параметры
 * Пример настройки для vim
  * Почему так делать не всегда надо :)		   * [[https://twitter.com/gvanrossum/status/737438918799282178|Pep8 is dead, long live pycodestyle!]], [[https://pycodestyle.readthedocs.io/en/latest/|pycodestyle]]
 * [[https://www.pylint.org|pylint]]
 * Почему так делать не всегда надо :)
Строка 30: Строка 23:
Магические числа
=== Аннотирование ===

[[py3tut:controlflow.html#function-annotations]]

https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep526
Строка 33: Строка 34:
https://wiki.python.org/moin/DocumentationTools#Automatic_Python_API_documentation_generation_tools
Строка 34: Строка 37:
 * Промежуточное: [[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/|пример]])
  . /!\ Устарело?
Строка 37: Строка 41:
  * [[http://www.mkdocs.org/|MkDocs]]
  * [[http://sphinx-doc.org/|sphinx]]
  * [[http://sphinx-doc.org/extensions.html|Дополнения]]
   * Книга «[[https://sphinx-ru.readthedocs.org/ru/latest/index.html|Генератор документации Sphinx]]»		   * [[http://www.mkdocs.org/|MkDocs]] сайт-генератор
 * [[http://sphinx-doc.org/|sphinx]]
  * [[http://sphinx-doc.org/extensions.html|Дополнения]]
  * Книга «[[https://sphinx-ru.readthedocs.org/ru/latest/index.html|Генератор документации Sphinx]]»

== Д/З ==
 * Переработать имеющийся код проекта в соответствие с `flake8`
  * создать настроечный файл, в котором изменить умолчания, если они не соответствуют дисциплине разработки
## * Переработать внутреннюю документацию в соответствие с выбранной системой документирования

Стиль программирования, комментарии и документирование

Оформление кода

Основная ссылка: pep-0008 — рекомендации к оформлению кода.

Анализаторы кода:

Комментарии

  • Не «что» и «как», а «зачем» и «почему»
  • Комментарии vs. код на Python (это не Си же)
  • Комментарии vs. строки документации

  • Выковыривание комментариев с помощью inspect.getcomments()

Магические числа

Аннотирование

controlflow.html

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

Д/З

  • Переработать имеющийся код проекта в соответствие с flake8

    • создать настроечный файл, в котором изменить умолчания, если они не соответствуют дисциплине разработки

LecturesCMC/PythonDevelopment2019/08_StyleAndDocumenting (последним исправлял пользователь FrBrGeorge 2019-04-12 15:26:58)