Главная » Java » Дополнительные замечания, документирование в java

0

 

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

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

Преодолеть проблему взаимного несоответствия комментариев и изменяющегося во времени кода помогут также средства определения стандартных текстовых маркеров, которые размещаются в коде для привлечения внимания читателя и программ-генераторов. Например, при добавлении в состав класса нового метода можно снабдить последний черновым комментарием, требующим последующей доработки группой подготовки технической документации: /**

* …   черновик   …

 * ©docissue Вася,   взгляни сюда и исправь!

*/

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

 

Источник: Арнолд, Кен, Гослинг, Джеймс, Холмс, Дэвид. Язык программирования Java. 3-е изд .. : Пер. с англ. – М. : Издательский дом «Вильяме», 2001. – 624 с. : ил. – Парал. тит. англ.

По теме:

  • Комментарии