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