¿A menudo ve en la documentación de la API (como en 'javadoc of public functions' por ejemplo) la descripción de los "límites de valor", así como la documentación clásica?documentación de API y "límites de valor": ¿concuerdan?
Nota: No estoy hablando de comments within the code
por "límites de valor", quiero decir:
- hace un parámetro puede apoyar a un valor nulo (o una cadena vacía, o .. .)?
- ¿un 'valor de retorno' puede ser nulo o está garantizado que nunca será nulo (o puede ser "vacío", o ...)?
muestra:
Lo veo a menudo (sin tener acceso al código fuente) es:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* @param aReaderNameRegexp filter in order to return only reader matching the regexp
* @return array of reader names
*/
String[] getReaderNames(final String aReaderNameRegexp);
Lo que gusta ver sería:
/**
* Get all readers name for this current Report. <br />
* <b>Warning</b>The Report must have been published first.
* @param aReaderNameRegexp filter in order to return only reader matching the regexp
* (can be null or empty)
* @return array of reader names
* (null if Report has not yet been published,
* empty array if no reader match criteria,
* reader names array matching regexp, or all readers if regexp is null or empty)
*/
String[] getReaderNames(final String aReaderNameRegexp);
Mi punto es:
Cuando uso una biblioteca con una función getReaderNames(), a menudo ni siquiera necesito leer la documentación de la API para adivinar qué hace. Pero necesito estar seguro cómo usarlo.
Mi única preocupación cuando deseo utilizar esta función es: ¿qué debo esperar en términos de parámetros y valores devueltos? Eso es todo lo que necesito saber para configurar de forma segura mis parámetros y probar con seguridad el valor de retorno, sin embargo, casi nunca ver ese tipo de información en la documentación de la API ...
Editar:
Esto puede influir en el uso o no para checked or unchecked exceptions.
¿Qué opinas? límites de valor y API, ¿pertenecen juntos o no?
Te sorprenderá la frecuencia con la que los desarrolladores no actualizan sus javadocs cuando cambian la semántica de un método ... Lo he visto MUCHO. Dicho esto, los marcos y el lenguaje en sí mismos suelen ser buenos. –
Las nuevas anotaciones: impresionantes si se producen, pero aún necesita documentar cuál es la semántica de un valor nulo con decir @Nullable. Encuentro que es mejor ser muy explícito sobre lo que pasará nulo en realidad, y @Nullable solo indica que está permitido, no lo que hace. –
@Mike Stone estuvo de acuerdo, parece que la documentación es obligatoria después de todo ... En cuanto al javadoc, estoy de acuerdo: de hecho, en mi proyecto de 200 desarrolladores, el javadoc para aplicaciones públicas rara vez está documentado. (Suspiro!) – VonC