documentación de API y "límites de valor": ¿concuerdan?

Question

¿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?

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?

Answer 1

Creo que puede pertenecen pero no necesariamente tienen para pertenecer a la familia. En su escenario, parece que tiene sentido que los límites estén documentados de tal manera que aparezcan en la documentación de la API generada y en intellisense (si el idioma/IDE lo admiten).

Creo que también depende del idioma. Por ejemplo, Ada tiene un tipo de datos nativo que es un "entero restringido", donde define una variable entera e indica explícitamente que solo (y siempre) estará dentro de un cierto rango numérico. En ese caso, el tipo de datos en sí mismo indica la restricción. Todavía debería ser visible y detectable a través de la documentación API e intellisense, pero no sería algo que el desarrollador tenga que especificar en los comentarios.

Sin embargo, los lenguajes como Java y C# no tienen este tipo de entero restringido, por lo que el desarrollador debería especificarlo en los comentarios si se tratara de información que debería formar parte de la documentación pública.

Answer 2

Creo que sí, y siempre han puesto comentarios en los archivos de encabezado (C++) en consecuencia.

Además de los comentarios de entrada/salida/devolución válidos, también observo qué excepciones serán lanzadas por la función (ya que a menudo quiero usar el valor de retorno para ... bien devolviendo un valor, prefiero las excepciones sobre los códigos de error)

//File: 
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list 
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method. 
//Exceptions: 
//except::FileNotFound 
//except::InvalidFile 
//except::InvalidParams 
//except::CreationFailed 
Texture *GetTexture(const std::string &File); 

Answer 3

Creo que ese tipo de condiciones de contorno más definitivamente pertenecen a la API. Sin embargo, yo (y con frecuencia lo haré) daré un paso más e indicaré QUÉ significan esos valores nulos. O indico que arrojará una excepción, o explico cuáles son los resultados esperados cuando se transfiere el valor límite.

Es difícil recordar hacer esto siempre, pero es algo bueno para los usuarios de su clase. También es difícil mantenerlo si el contrato presenta cambios en el método (como valores nulos cambiados a no permitidos) ...también debe ser diligente para actualizar los documentos cuando cambie la semántica del método.

Answer 4

@Fire Lancer: ¡Derecho! Me había olvidado de excepción, pero me gustaría verlos mencionados, especialmente la marcada 'en tiempo de ejecución' excepción de que este método público podría lanzar

@ Mike piedra:

que tiene que ser diligente también para actualizar el documentos cuando cambias la semántica del método.

Mmmm Por supuesto, espero que la documentación API pública es por lo menos actualizado siempre que un cambio - que afecta el contrato de la función - se lleva a cabo. De lo contrario, esas documentaciones API podrían desaparecer por completo.

Para agregar alimentos a la suya pensamientos (e ir con @ Scott Dorman), sólo se tropiezan con the future of java7 annotations

Lo que hace que significa? Que ciertas 'condiciones de contorno', en lugar de estar en la documentación, deberían estar mejor en la API en sí, y utilizarse automáticamente, en tiempo de compilación, con el código generado 'afirmativo' apropiado.

De esta manera, si hay un '@CheckForNull' en la API, el autor de la función puede salirse con la suya sin siquiera documentarlo. Y si el cambio semántico, su API reflejará ese cambio (como 'no más @CheckForNull' por ejemplo)

Ese tipo de enfoque sugiere que la documentación, para 'condiciones de contorno', es una ventaja adicional en lugar de una práctica obligatoria .

Sin embargo, eso no cubre los valores especiales del objeto de retorno de una función. Para eso, todavía se necesita una completa documentación.

Answer 5

Pregunta 1

¿A menudo se ven en la documentación API (como en 'javadoc de la función pública', por ejemplo) la descripción de los "límites de valor", así como la documentación clásico?

Casi nunca.

Pregunta 2

Mi única preocupación cuando quiero utilizar esta función es: ¿qué debo esperar en términos de parámetros y valores de retorno? 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 ...

Si usara una función no está bien que se puede esperar a RuntimeException arrojado por el método o RuntimeException en otra parte (a veces muy lejos) del programa.

Comentarios como @param aReaderNameRegexp filter in order to ... (can be null or empty) me parece una forma de implementar Design by Contract en un lenguaje de los seres humanos dentro de Javadoc.

Usando Javadoc para hacer cumplir Diseño por contrato fue utilizado por iContract, ahora resucitado en JcontractS, que le permiten especificar invariantes, precondiciones, post-condiciones, de manera más formal en comparación con el lenguaje de los seres humanos.

Pregunta 3

Esto puede influir en el uso o no de excepciones activada o desactivada. ¿Qué opinas? límites de valor y API, ¿pertenecen juntos o no?

lenguaje Java no tiene una característica de diseño por contrato, por lo que podría tener la tentación de utilizar Execption pero estoy de acuerdo con usted sobre el hecho de que usted tiene que ser consciente de When to choose checked and unchecked exceptions. Probablemente podría usar el IllegalArgumentException, sin marcar, o podría usar pruebas unitarias, pero el principal problema es cómo comunicar a otros programadores que dicho código trata sobre el Diseño Por Contrato y debe considerarse como un contrato antes de cambiarlo demasiado a la ligera.