Почему документация имеет значение и почему вы должны включать ее в свой код

pochemu dokumentacziya imeet znachenie i pochemu vy dolzhny vklyuchat ee?v=1656565215

Существует множество аббревиатур, когда дело доходит до разработки программного обеспечения. KISS, DRY, SOLID… и так далее и так далее. Но когда дело доходит до документирования или комментирования вашего кода, нет простой крылатой фразы.

Почему так?

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

В этой статье я объясню, почему документирование вашего кода поможет стать лучшим разработчиком и поможет стать отличным членом команды.

На это ни у кого нет времени

Основная причина, почему код остается недокументированным, заключается во времени.

При разработке функции, которую необходимо завершить в течение определенного периода времени, у нас редко бывает момент, чтобы остановить все и сосредоточиться на документировании нашего кода.

Кроме разработки и написания самого кода, нам нужно пройти рецензирование кода, тесты автоматизации и добавить модульные тесты (чтобы назвать несколько вещей). Документация почти исключена из уравнения.

Это малейшее мнение о деталях, которое может иметь наибольшее значение в будущем.

Независимо от того, что вы разрабатываете, есть вероятность, что когда-нибудь вам или кому-нибудь из ваших коллег придется вернуться к этому. Когда наступит тот день, вы не будете так ярко вспоминать, что и почему написали.

И если вы помните, могут быть некоторые крайние случаи или конкретное использование, которые могут быть нечёткими. Очевидное решение документация.

Если вы потратите дополнительное время, чтобы написать надлежащее описание того, над чем вы работали, это сэкономит огромный количество времени в будущем.

В следующий раз, когда кто-нибудь захочет понять, что происходит внутри вашего кода, все, что вам нужно сделать, это указать им на документацию. Это сэкономит время, поскольку вам не нужно будет объяснять вещи, и это сэкономит время для них, поскольку они не будут зависеть от вас.

И, наконец, когда вам, как разработчику, нужно что-то понять об определенном аспекте кодирования, что вы делаете?

? Вы идете в документацию?

Хороший код не требует документации

Да, я знаю, я знаю… хорошо написанный код, который сжат и хорошо продуман, не требует документирования. Это читается как история.

Хотя это может быть так, это не отказывается от необходимости документации, и вот почему:

  1. Мы все слишком знакомы с надежностью кода, содержащего функцию. Глядя на один раздел кода, может быть не понятно, что есть другие разделы, которые глубоко связаны с ним.
  2. Каждая созданная вами служба имеет уникальный API. Чтобы написать, как использовать этот API, требуется документация, которую можно прочитать вне кода. Вы не хотите наполнять сам класс деталями о том, как использовать API.
  3. Коллеги, работающие в разных отделах (которые могут не являться разработчиками), могут захотеть понять, что вы делали и как это работает.
  4. Только само действие может заставить вас по-другому взглянуть на код, который вы написали. Объяснение того, что делает ваш код, заставит вас оценить его действительность и возможно рассмотреть возможность изменить вещи, если они не соответствуют вашим ожиданиям.
  5. Ради потомков
5jPNlmEKOGjTR294BEYE1stmTaQuIP38GzPM
«Человек пишет карандашом в блокноте со стружками карандаша» от Thought Catalog на Unsplash

Как написать хорошую документацию

Хорошая документация похожа на хороший блок кода. Кратко, просто и понятно. Вот несколько рекомендаций, которые вы можете придерживаться:

  • Поймите, на кого рассчитана документация. Это только для разработчиков? Есть ли более широкая аудитория? Понимание этого сэкономит ваше время, поскольку вы будете заранее знать, сколько подробно излагать в своих объяснениях.
  • Напишите короткий, но описательный фон, объясняя основные моменты создания. Это поможет читателям понять цель функции и определить ее соответствие тому, что они хотят знать.
  • Перечислите и опишите основные точки зрения вашей функции, не забудьте указать какие-либо зависимости, существующие с другими функциями.
  • Убедитесь, что есть метка времени, чтобы сообщить читателям о действительности документации. Кроме того, если вы используете некоторые библиотеки, обязательно добавьте их версии.
  • Будьте щедры на примерах кодирования, подробно описывая, как правильно использовать функцию, которую вы написали, и демонстрируйте ожидаемые результаты.

Примеры

Чтобы лучше понять, как выглядит хорошая документация, мы рассмотрим несколько замечательных примеров: Mozilla’s Developer Network (MDN), Django и Stripe.

ttMCqH73G7L0lkB4Pg5RTAjPcnH9Q2-bfCRN
Обратите внимание на быстрые ссылки вверху для упрощения навигации

В документации MDN можно четко увидеть, что каждая страница начинается с краткого пояснения на тему.

Затем переходит к детализации случаев использования и методов. Наконец, он показывает, какие браузеры совместимы с этой функцией, и дает ссылки на соответствующие материалы.

n8TyfIok8mUQEmt6OeypnOV6pVp-TwJRSFaH
В документации Stripe каждый предмет имеет фрагменты кода, которые можно просмотреть на разных языках кодирования.
6AgI3-4qhfO2BH7hrr0fXt8kbUScCjCI1KnV

Документация Django очень надежна. Независимо от вашего уровня кодирования, они начинают вас с обзора и учебных пособий.

Затем они рассматривают каждую тему, тщательно детализируя ее, предоставляя короткие и сжатые фрагменты кода, которые демонстрируют, что нужно сделать

Надеюсь, я смог подчеркнуть важность документации и дал вам несколько указаний по поводу того, как начать документировать свой код. Если у вас есть идея аббревиатуры для документации, не стесняйтесь делать это в комментариях ниже.

Возможно, РЕБЕНОК — Кeep ят ддокументированный?

Если вам понравилась эта статья, хлопайте, чтобы другие могли наслаждаться ею! ???

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *