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

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

Это даже всплывало в вопросах интервью:

Интервьюер: Когда вы должны документировать свой код?

Я: Всякий раз, когда непонятно?

Интервьюер: На самом деле мы документируем каждую строчку нашего кода.

Me: Oh.

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

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

Код — это документация

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

Возьмем этот тривиальный пример на питоне, который берет список людей и возвращает среднюю зарплату:

Даже для такого тривиального примера у нас есть несколько встроенных в код допущений, которые могут быть неочевидными. Как это исправить? Мы можем добавить некоторые документы!

Лучше? Фу! Нет. Столько шума.

Итак, как мы можем улучшить ситуацию? Ответ: делаем сам код документом:

Это гораздо более читабельно и не требует никакой документации, чтобы понять его намерения.

Мы можем сделать несколько вещей, которые помогут нам написать самодокументирующийся код:

  1. Используйте короткие функции с выразительными именами — я надеюсь, что каждый программист знает, что функции всегда должны быть короткими. Всякий раз, когда мы сталкиваемся с фрагментом кода, который трудно читать, мы можем поместить этот код в функцию с соответствующим названием, чтобы улучшить способность кода к самодокументированию.
  2. Используйте хорошие имена переменных. Именование, как гласит старая шутка, — это одна из двух самых сложных вещей в программировании. Имена переменных всегда должны способствовать самодокументированию кода.
  3. Используйте встроенные функции, когда это уместно. Все знают, что sum и len делают правильно? (Извините перед теми, кто не является питонистом, — у вашего выбранного языка наверняка будут эквиваленты). Поэтому мы должны использовать их вместо того, чтобы накатывать свои собственные, как в первом примере.
  4. Используйте выразительные языковые функции. Понимание списка, используемое для получения всех зарплат, может показаться странным новичку, но для опытных питонистов оно прекрасно выразительно и легко читается. Познакомьтесь со своим языком и выразительными возможностями, которые он предоставляет.

Так что мне больше никогда не придется писать документацию, верно?

Не так быстро. По возможности следует избегать документации, но иногда небольшой комментарий для объяснения проектного решения является правильным решением.

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

Я считаю самодокументирование фантастической целью, к которой нужно стремиться, это помогает улучшить код, который я пишу каждый день.

Будет странный случай, когда комментарии потребуются во имя юмора. Мой любимый пример — от коллеги-программиста на C, которому надоело иметь дело с Windows (моя цензура):