Это одна из самых обсуждаемых тем среди разработчиков: документировать или не документировать код?
Мне казалось, что эта тема уже закрыта и давно ясно, что, за исключением некоторых редких случаев (разработка публичного API), документация необязательна. Я думал так до тех пор, пока не увидел code review, где проверяющий обозначил недостаток документации как проблему. Прав ли он?
Я был одним из тех, кто документировал свой код… или по крайней мере пытался. Я был убежден, что код должен быть задокументирован, потому что это могло служить подсказкой для себя в будущем либо для других разработчиков, которым повезло работать с моим кодом. Хотя в то же самое время, я всегда понимал, что документация неактуальна. И тогда я задумался: какой смысл в документировании кода, если она всегда становится неактуальной?
Несколько лет тому назад, я прочел книгу “Чистый код”.
Тогда я отчетливо понял, что нет необходимости документировать код, если вы кодируете документацию.
Говоря это, я имею в виду использование смысловых имен переменных и методов. Если имя переменной уже говорит об информации, которую она содержит, а имя метода говорит, что именно метод делает, то отстутствует необходимать разбираться и документировать, что делает твой код.
Убирайте как можно больше кода из методов, даже если в итоге получается метод, состоящий из только 3 или 4 строк. Каждый метод должен делать одну и только одну вещь. И имя должно объяснять, что именно.
Каждый член класса должен иметь имя, которое просто после прочтения дает понять, какую информацию можно там найти. То же самое касается и переменных и входных параметров.
Следуя этим простым шагам, вы можете получить такой код, что документацию можно будет прочитать в этом же коде.
Да, я знаю, что бывают ситуации, когда нужно написать сложный алгоритм или вы скопировали код из интернета, который сложный, непонятный либо тяжело переводим в простые методы. Да, из любого правила есть исключения.