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

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

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

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

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

Резюме

Мастерство писателя заключается в создании контекста, в котором могут думать читатели.

Эдвин Шлоссберг

Мы пишем код для того, чтобы передать информацию. Код без доку% ментации опасен и малоинформативен. Его трудно сопровождать. Плохая документация также создает проблемы: она либо вводит чита% теля в заблуждение, либо делает программу ненадежной и требующей дополнительных разъяснений.

Часто единственной документацией по программе оказывается ее соб% ственный код. Если код самодокументируемый и написан ясно, это от% части решает проблему. Самодокументируемый код не возникает из ничего; он требует тщательного обдумывания. Получаемый при этом код выглядит так, будто написать его было просто.

Грамотное программирование – это один из способов (весьма экстре% мальный) написания самодокументируемого кода. Менее экстремаль% ный подход требует участия программных инструментов документи% рования. Эти инструменты легко создают документацию по API, но не всегда могут заменить письменные спецификации.