«Резервный» javadoc - желательно для API с открытым доступом?

Question

Когда вы видите что-то вроде этого:

/** 
* Gets the Person's identifier. 
* 
* @return The person identifier. 
*/ 
public long getId() 

многие из вас могут подумать «какой смысл повторять, что код подразумевает»? Я лично согласен и не стал бы писать такой комментарий, если бы мой код видел и использовал только люди в моей компании.

Если, однако, я писал, скажем, библиотеку Apache Commons, я думаю, можно утверждать, что она улучшает опыт программиста-потребителя. Наблюдение доступных методов с пустым пространством в javadoc просто создает ощущение отсутствия дружелюбия/зрелости/поддержки для потребителя, которое может повлиять на их уверенность в вашем api и в конечном итоге выбрать конкурента.

Есть ли разница в желательности избыточного javadoc для API-интерфейсов, ориентированных на общественность и не относящихся к публике?

Answer 1

Если вы имеете в виду это как библиотеку, то да, все общедоступные методы и поля должны быть задокументированы, потому что это то, из чего генерируется документация html.

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

Answer 2

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

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

Это приводит к тому, что вы указываете: «все, что я делаю, это отказаться от значимого владения моими данными, повеселиться». Больше нечего сказать, потому что метод делает не более того.

Устраните эту проблему, предоставив свои объекты своим данным. Не создавайте аксессуры для чтения кому-либо, создавайте методы, которые выполняют требуемые действия и управляют внутренними данными. Создавайте методы рендеринга, которыми обладает объект, а не там, где он передает dava eer сторонней системе с пожиманием плечами.

Другая возможная причина заключается в том, что у вас есть метод, который звучит очень просто, например «получить идентификатор клиента», но на практике это делает. У этого есть цель, он захватывает кучу бизнес-логики, и вы только что записали результат в описании.

Исправить это, задокументировав вещи. Если предположить, что это больше, чем просто «читать ID», мне нужно знать еще некоторые вещи о вашем API:

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

Сейчас я знаю, что у него есть удостоверение ... что-то вроде ... что я могу использовать для ... не знаю. Определить вещи? К, гм, что-то, наверное?

Вместо этого я хочу знать, что это уникальный идентификатор, что он является стабильным, и что он потенциально повторно используется, поэтому я не могу его запереть на моей стороне, не подписываясь также на уведомление об удалении пользователя и что для него требуется обратная связь с базой данных, но операция базы данных O (1), поэтому производительность означает минимум два контекстных переключателя и максимум 12xRTT в сети.

Это полезные вещи, которые вы должны внести в свою документацию. Затем у вас есть @returns the ID of the person в самом конце, как камень. Я должен знать это, конечно, но есть намного больше, что мне нужно знать, чтобы использовать это эффективно и безопасно.