> For the complete documentation index, see [llms.txt](https://braydie.gitbook.io/how-to-be-a-programmer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://braydie.gitbook.io/how-to-be-a-programmer/ru/1-beginner/team-skills/05-how-to-document-wisely.md).

# Как документировать правильно

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

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

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

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

Это не облегчает работу ответственным программистам. Как писать самодокументируемый код? Что это вообще значит? Это значит:

* Писать код, думая о том, что кому-то придется его читать
* Применять золотое правило выше
* Выбирать решение, которое очевидно, даже если менее очевидное решение быстрее
* Жертвовать небольшими оптимизациями вместо того, чтобы делать код менее понятным
* Думать о читателе кода и тратить больше своего драгоценного времени на то, чтобы ему было проще
* Никогда не называть функции `foo`, `bar` или `doIt`!

Следующее: [Как работать с плохим кодом](/how-to-be-a-programmer/ru/1-beginner/team-skills/06-how-to-work-with-poor-code.md)