Документирование

Хорошая документация — свидетельство профессиональной гордости, выражаемой

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

Часто назначение метода очевидно. Часто, но не всегда. Если метод возвращает значениеполя объекта – тут документировать особо нечего. Хотя, можно написать, что именно он возвращает, иногда это бывает полезно, особенно, когда объект использует кто-то, незнакомый с его внутренней структурой. Но даже если метод размером всего строк в пять-шесть – уже стоит описать его функции. Есть такое понятие – замыливание взгляда. Когда смотришь на код, и не видишь очевидных вещей. Тогда документация может оказать очень большую помощь. Можно потратить полчаса на копание в коде, а можно пару минут на чтение документации метода. В которой описано, как он себя ведет и почему.

Дата добавления: 2015-08-27