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

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

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

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

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

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

• Писать код, думая о том, что кому-то придется его читать

• Применять золотое правило выше

• Выбирать решение, которое очевидно, даже если менее очевидное решение быстрее

• Жертвовать небольшими оптимизациями вместо того, чтобы делать код менее понятным

• Думать о читателе кода и тратить больше своего драгоценного времени на то, чтобы ему было проще

• Никогда не называть функции foo, bar или doIt!

Следующее: Как работать с плохим кодом