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

language-agnostic documentation

Question

¿Suele ver 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 comentarios dentro del código

Por "límites de valor", quiero decir:

• ¿un parámetro puede soportar 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 que a menudo veo (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 me gustaría 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 de cómo usarlo .

Mi única preocupación cuando quiero usar 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 manera segura mis parámetros y probar de forma segura el valor de retorno, sin embargo, casi nunca veo ese tipo de información en la documentación de API ...

Editar:

Esto puede influir en el uso o no de las excepciones marcadas o no .

Qué piensas ? límites de valor y API, ¿pertenecen juntos o no?

Answer 1

@Fire Lancer: ¡Correcto! Me olvidé de la excepción, pero me gustaría que se mencionen, especialmente la excepción de ''tiempo de ejecución'' no comprobada que este método público podría arrojar

@ Mike Stone:

también debe ser diligente para actualizar los documentos cuando cambie la semántica del método.

Mmmm Espero que la documentación pública de la API esté al menos actualizada cada vez que ocurra un cambio que afecte el contrato de la función. De lo contrario, esas documentaciones API podrían desaparecer por completo.

Para agregar comida a tus pensamientos (y ve con @Scott Dorman), me tropiezo con el futuro de las anotaciones java7

Qué significa eso ? 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 forma, si un ''@CheckForNull'' está en la API, ¡el autor de la función puede salirse con la suya sin siquiera documentarla! 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 las ''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 documentación completa .

Answer 2

Creo que pueden estar juntos, pero no necesariamente tienen que estar juntos. 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 un 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 3

Creo que ese tipo de condiciones límite 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 lanzará una excepción, o explico cuáles son los resultados esperados cuando se pasa 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 que los valores nulos se cambian a no permitirse) ... también debe ser diligente para actualizar los documentos cuando cambie la semántica del método.

Answer 4

Creo que sí, y siempre han colocado 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 devolver 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 5

Pregunta 1

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

Casi nunca.

Pregunta 2

Mi única preocupación cuando quiero usar 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 manera segura mis parámetros y probar de forma segura el valor de retorno, sin embargo, casi nunca veo ese tipo de información en la documentación de API ...

Si utilicé una función no correctamente, esperaría que el método arrojara una RuntimeException o una RuntimeException en otra parte (a veces muy lejana) del programa.

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

El uso de Javadoc para hacer cumplir el diseño por contrato fue utilizado por iContract , ahora resucitado en JcontractS , que le permite especificar invariantes, condiciones previas, condiciones posteriores , de forma más formal en comparación con el lenguaje del ser humano.

Pregunta 3

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

El lenguaje Java no tiene una característica Diseñar por contrato, por lo que es posible que tenga la tentación de utilizar Execption pero estoy de acuerdo con usted sobre el hecho de que debe conocer cuándo elegir las excepciones marcadas y no marcadas . Probablemente pueda usar IllegalArgumentException , IllegalStateException , o puede usar pruebas unitarias, pero el problema principal es cómo comunicarle a otros programadores que dicho código trata sobre Design By Contract y debe considerarse como un contrato antes de cambiarlo demasiado a la ligera.