В своих Java-приложениях я всегда комментирую свои классы и методы, чтобы указать, для чего они предназначены. Проблема, с которой я часто сталкиваюсь, заключается в документировании полного процесса, в результате чего процесс распределяется по нескольким классам. Мне нужно задокументировать, как все части работают вместе, чтобы дать простой обзор того, как что-то работает.
Я нахожу проблематичным то, ГДЕ я пишу эту документацию. С таким же успехом я мог бы написать его в отдельном файле, таком как документ Word, но документация имеет тенденцию отчуждаться от фактического кода, и возможна рассинхронизация. С другой стороны, если я задокументирую это в одном файле кода Java, кому-то, читающему один из зависимых классов, будет сложно узнать, как этот класс вписывается в общий процесс, если только он не знает о документации в классе, где я написал это. Возможное решение состоит в том, чтобы просто включить ссылку в каждый класс, составляющий весь процесс, и просто обозначить один из классов как «основной» класс, из которого исходит документация.
Или есть лучший альтернативный подход к тому, как я должен это делать?
ИЗМЕНИТЬ:
Например, у вас есть мобильное приложение, которое загружает данные на сервер, а затем вы загружаете данные с сервера на другое устройство. У вас есть процесс, который охватывает три компонента (отправляющее мобильное устройство, сервер и принимающее мобильное устройство). Ни один из них нельзя в действительности считать «отправной точкой в общем процессе передачи данных, поэтому при документировании этого процесса куда пойдет эта документация?
@link
для связи других классов? - person AllTooSir   schedule 29.07.2013