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

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

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

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

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

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

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://braydie.gitbook.io/how-to-be-a-programmer/ru/1-beginner/team-skills/05-how-to-document-wisely.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.