Не документируйте код. Кодируйте документацию

Это одна из самых обсуждаемых тем среди разработчиков: документировать или не документировать код?

Мне казалось, что эта тема уже закрыта и давно ясно, что, за исключением некоторых редких случаев (разработка публичного API), документация необязательна. Я думал так до тех пор, пока не увидел code review, где проверяющий обозначил недостаток документации как проблему. Прав ли он?

Я был одним из тех, кто документировал свой код… или по крайней мере пытался. Я был убежден, что код должен быть задокументирован, потому что это могло служить подсказкой для себя в будущем либо для других разработчиков, которым повезло работать с моим кодом. Хотя в то же самое время, я всегда понимал, что документация неактуальна. И тогда я задумался: какой смысл в документировании кода, если она всегда становится неактуальной?

Несколько лет тому назад, я прочел книгу “Чистый код”.

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

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

Убирайте как можно больше кода из методов, даже если в итоге получается метод, состоящий из только 3 или 4 строк. Каждый метод должен делать одну и только одну вещь. И имя должно объяснять, что именно.

Каждый член класса должен иметь имя, которое просто после прочтения дает понять, какую информацию можно там найти. То же самое касается и переменных и входных параметров.

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

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