Я всегда слышал, что один из лучших способов стать разработчиком — больше читать код. В частности, идея состоит в том, что вы должны читать код, написанный лучшими, более опытными разработчиками. Это всегда имело для меня смысл в теории, но я никогда не применяла эту теорию на практике.
Я просто не работал над проектами, в которых документация отдавала предпочтение созданию дополнительных функций. Я собирал достаточно кода Python, чтобы заставить что-то работать, а затем сразу же переключал внимание на то, чтобы протолкнуть эту одну вещь глубже в производственную кроличью нору. В моей отрасли правда такова, что многие клиенты не беспокоятся о сопровождении кода. У них есть немедленный зуд, который им нужно почесать, и часто моя работа заключается в том, чтобы почесать этот зуд как можно быстрее, чтобы мы могли сосредоточиться на других зудах, которые нужно почесать.
Это рецепт создания значительного количества технического долга, но, увы, это также мир консалтинга. Если вы консультант, скорее всего, у вас большой опыт борьбы с пожарами в мусорных баках, возникшими в результате наследования чужого кода или рабочих процессов. На самом деле это не чья-то вина, это просто побочный продукт стремительных (а иногда и близоруких) целей, которые ставятся перед краткосрочными консультационными проектами. Где-то там есть бедняга, который унаследовал мой собственный пожар в мусорном баке (извините!).
Для меня все изменилось, когда я работал над долгосрочным заданием, когда команда инженеров данных переносила свой рабочий процесс ETL на Airflow. Я взялся за проект, который включал в себя создание неофициального плагина для Airflow для взаимодействия с Tableau Server, и впервые я написал достаточно кода, чтобы сделать документацию важной проблемой.
Я из тех людей, которым нравится знать лучший способ что-то сделать, поэтому я начал выискивать другие плагины Airflow на Github. Есть из чего выбрать: https://github.com/airflow-plugins
Что-то, что я сразу же заметил, было то, насколько хорошо документированы все плагины, что побудило меня копнуть немного дальше. Оказывается, в репозитории плагинов airflow есть рекомендации по документированию плагинов, а также о том, как структурировать любой репозиторий плагинов, который вы хотите внести. Как описано в их руководстве по внесению вклада, классы содержат строки документации, подобные приведенной ниже:
Давайте быстро пробежимся по некоторым вещам, которые мне действительно нравятся в этом формате.
- Дается краткое описание класса.
- Роль каждого параметра четко определена.
- Тип каждого параметра четко определен.
- Никакого флуда, и все по делу.
- Я могу легко адаптировать это к своему собственному коду, чтобы любому другому было легче освоить код, который я написал.
Я использую этот формат сейчас даже при разработке блокнота Jupyter на лету. В настоящее время я работаю над проектом с остановками, иногда с двух- или трехнедельными перерывами между одной частью проекта и другой. Эта новая привычка, которую я позаимствовал из документации плагинов Airflow, уже принесла свои плоды, так как я обнаружил, что читаю свою собственную документацию, чтобы вернуться к скорости работы с ноутбуками, которые я разработал более месяца назад.
Результатом этих крошечных усилий, которые я приложил к документированию своего кода, стало то, что я могу очень быстро взяться за дело.
Этот шаблон документации намного лучше, чем случайно организованные описания длиной в абзац, которые я писал. На данный момент я даже не хочу смотреть на код, который написал год назад. Это ужасно.
Чтобы отдать должное, кажется, что этот шаблон получен из соглашений о строках документации, описанных в PEP 257.
Ниже вы найдете пример того, как я документирую класс для стороннего проекта, над которым работаю. Я надеюсь, что кто-то найдет этот образец документации таким же полезным, как и я!
