Получите лучшее из обоих миров с помощью этой очень старой парадигмы программирования
Вы когда-нибудь слышали фразу: самодокументированного кода не существует? Что ж, подождите, потому что я собираюсь показать вам обратное - вроде того.
Первоначально представленный Дональдом Кнутом около 1984 года, грамотное программирование считается парадигмой программирования, которая позволяет вам объединять документацию вашего кода, написанную на естественном языке, с фрагментами и оригинальными частями вашего исходного кода. Он работает таким образом, что в качестве результата компиляции вы можете либо запустить код, либо сгенерировать интерактивную версию документации (то есть версию HTML).
Хотя огромные базы кода было бы очень неудобно писать таким образом, есть аргумент в пользу более мелких компонентов, таких как библиотеки или компоненты. Например, если вы веб-разработчик, создающий компонент React, вы можете воспользоваться преимуществами грамотного программирования. Вы можете структурировать как документацию, так и фактический исходный код таким образом, чтобы любой, кто пытается понять, как его использовать, может органично изучить, прочитав сгенерированную документацию.
Я знаю, прямо сейчас я говорю, что это звучит как прославленная версия Javadocs, но дайте мне шанс, это больше, чем кажется на первый взгляд.
Почему это лучше, чем инструменты для создания документации?
Javadocs позволяет создавать документацию из хорошо составленных комментариев. У вас есть формат, которому нужно следовать, и если вы все сделаете правильно, конечный результат может быть действительно очень хорошим.
Однако получившаяся документация с подобными инструментами имеет серьезный недостаток: создается впечатление, что вы просматриваете зеркальную версию исходного кода. Вы получите все подробности, но вы должны знать, где их искать.
Это не органично, не интуитивно, а очень механически и машинно.
Однако именно здесь в игру вступает грамотное программирование: вместо того, чтобы помещать объяснение внутри кода, вы помещаете код внутри объяснения. Это очень важное отличие делает так, что когда вы просматриваете окончательный результат, вы можете прочитать историю, которая показывает вам, как все работает.
Это похоже на чтение статьи или книги о вашей библиотеке, вместо того, чтобы изучать ее внутреннюю логику в надежде, что вы не пропустили соединение.
Быстрый пример
Для быстрого практического примера того, как работает грамотное программирование, единственное, что вам нужно знать прямо сейчас, это следующее:
- Для большинства языков программирования существует множество доступных инструментов CLI, позволяющих создавать документацию с использованием вашего любимого языка разметки, а затем правильно ее переводить.
- В документации по разметке вы будете использовать специальные теги, которые будут идентифицировать блоки кода. Эти блоки кода будут извлечены в процессе запутывания.
Следующий файл содержит мой написанный код и документацию, все в одном.
Хотя это очень простой пример, обратите внимание, как я смог разделить то, что обычно было бы одним файлом, на три разных части, используя эти специальные теги (т.е. функции sum и subtract должны находиться в одном файле с именем mylib.js и последнем фрагмент кода фактически является частью функции subtract).
Таким образом, я могу сосредоточиться на объяснении, как я хочу, не позволяя структуре кода влиять на мое повествование.
С этим файлом и с помощью утилиты pyWeb (грамотный инструмент, написанный на Python) я могу запустить следующие строки для анализа и извлечения того, что мне нужно:
$ python3 -m pyweb my-lib.w $ rst2html5.py my-lib.rst my-lib.html
Первая строка переводит мой .w файл в два других файла: mylib.js (потому что я так назвал его в документации) в процессе, известном как запутывание, и mylib.rst, который уже можно рассматривать как окончательную документацию ( через процесс, известный как плетение), но с помощью rst2html, который вы можете скачать здесь, я превратил его в HTML.
Выходы - это мой файл JavaScript:
И сама документация:
Краткое введение в теги и макросы
Суть файла .w, кроме самой документации, - это макросы (по сути все, что начинается с @).
Вот основные из них, которые вам понадобятся для понимания кода:
@oозначает «вывод». Другими словами, там, где вы должны экспортировать следующий блок кода. Если вы повторяете имя файла в разных экземплярах, этот код будет добавлен (что и происходит в приведенном выше примере).@{и@}открывают и закрывают блоки кода. По сути, все внутри них - это код. Это также относится к пробелам, которые помогают с отступами, особенно если вы пишете код Python.@<и@>открывают и закрывают встроенное включение. Это фрагменты, которые вы можете извлечь и расширить где-нибудь еще. Обратите внимание, что я добавил один из них в функциюsubtract.@dопределяет встроенное определение. Он используется для определения блока кода, который будет включен с использованием предыдущих элементов.
Конечно, спецификации содержат больше макросов, но теперь вы можете вернуться к основному примеру и снова проверить его, это будет иметь гораздо больший смысл.
Когда бы вы использовали грамотное программирование?
Послушайте, я не призываю вас начинать полноценную платформу с нуля, используя грамотное программирование, это не имеет смысла. Но опять же, возможно, вашей платформе не нужен такой уровень подробной документации, поскольку она не предназначена для использования другими.
Однако, если вы создаете код, который будет использоваться третьими сторонами, или, другими словами, если вы создаете библиотеки (подумайте о модулях pip, пакетах NPM, компонентах React и любом другом типе модульного кода), тогда хорошо написанный документация имеет первостепенное значение для обеспечения принятия пользователями.
Дело в том, что, как и в случае с TDD, сложно переключиться на что-либо, кроме кодирования, поскольку ваш первый шаг к созданию этих библиотек является трудным. Но если, как в случае с TDD, вы прилагаете усилия и в этом случае создаете документацию во время написания кода, это может даже помочь вашему процессу ментального моделирования.
Это не то же самое, что 10 минут подумать, а затем перейти к проверке своей гипотезы, чем потратить 20 минут на «воплощение» этих идей в реальные слова и на то, чтобы увидеть, насколько последовательными они в конечном итоге окажутся.
Использование грамотного программирования для наших компонентов React
Просто чтобы дать вам более практический пример, здесь я собираюсь переписать этот компонент, которым поделился на Bit.dev:
По сути, это кнопка, которую вы можете добавить в свое приложение и установить для нее внешний вид и поведение по умолчанию в зависимости от ее релевантности. Вы можете увидеть полный исходный код здесь, и, как вы понимаете, это несложный компонент. Однако это не задокументировано, по сути, даже не прокомментировано.
Итак, если бы я придерживался грамотного подхода, я мог бы написать что-то вроде этого:
Если вы сможете мысленно проанализировать это, вы заметите несколько вещей:
- Он смешивает примеры и показывает вам фрагменты кода и стили CSS, говоря о конкретных разделах компонента (в примере я добавил объяснение только для «важной» кнопки, но вы можете сделать то же самое для остальных).
- Это не повторение кода, я пишу код в одном месте, а затем ссылаюсь на тот же фрагмент в другом месте. Таким образом, нет дублирования кода, то, что вы пишете, - это то, что вы получаете.
- Вы даже можете написать образец кода, который не будет «экспортироваться». Это код, предназначенный только для самой документации, но этот код также может извлекать разделы из вашего основного исходного кода.
- Я не только создаю код TSX, но и пишу здесь CSS.
С помощью этих двух команд я получаю как свою HTML-документацию, так и исходный код, готовые к экспорту обратно в Bit:
$ python3 -m pyweb extended-buttons.w $ rst2html5.py extended-buttons.rst extended-buttons.html
Для простоты вот 2 скриншота исходного кода и сгенерированного документа:
Полностью функциональный с одной стороны и полностью читаемый и понятный с другой, и оба они взяты из одного места.
Грамотное программирование определенно не является ответом на все ваши проблемы с документацией, и если ваша кодовая база достаточно велика, вам придется иметь дело с несколькими .w файлами и импортировать их так же, как и с кодом.
Но для определенной группы разработчиков, которые постоянно создают модули и делятся своим кодом, такой подход может значительно сэкономить время.
Конечно, если вам нужно вернуться и обновить код или исправить ошибку, разделение вашей функции на 3 части может стать реальной проблемой. Так что это также может быть интересным вариантом, когда ваш код станет достаточно стабильным и все, что вам нужно, - это написать надлежащую документацию.
Что вы думаете? Дадите ли вы шанс грамотному программированию?
