la documentación de la api y el valor de "límites":¿coinciden?

Question

¿Usted ve a menudo en la documentación de la API (como en 'javadoc de las funciones públicas", por ejemplo) la descripción de los "límites de valor", así como el clásico de la documentación ?

Nota: Yo no estoy hablando de los comentarios dentro del código

Por "límites de valor", me explico:

• hace un parámetro puede admitir un valor nulo (o una Cadena vacía, o...) ?
• hace un 'valor de retorno' puede ser nulo o está garantizado para nunca ser null (o puede ser "vacío", o...) ?

Ejemplo:

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 Me como para 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 yo uso una biblioteca con una getReaderNames() función en ella, yo a menudo no es necesario leer la documentación de la API para adivinar de qué se hace.Pero necesito estar seguro de que cómo usarlo.

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 necesitas saber para seguridad de configuración de los parámetros y de forma segura a prueba el valor de retorno, sin embargo, casi nunca los veo ese tipo de información en la documentación de la API...

Editar:

Esto puede influir en el uso o no de activada o desactivada excepciones.

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

Answer 1

Creo que puede pertenecen juntos, pero no necesariamente han pertenecer juntos.En el escenario, parece que tiene sentido que los límites están documentados en la forma en que aparecen generado en la documentación de la API y intellisense (si el idioma/IDE de apoyo).

Creo que no depende de la lengua.Por ejemplo, Ada tiene un tipo de datos nativo que es un "restringido entero", donde se define una variable de tipo entero y explícitamente indican que sólo (y siempre) dentro de un cierto intervalo numérico.En ese caso, el tipo de datos sí indica la restricción.Debe ser visible y detectable a través de la documentación de la API y de intellisense, pero no sería algo que un desarrollador tiene que especificar en los comentarios.

Sin embargo, en lenguajes como Java y C# no tiene este tipo de restricciones entero, por lo que el desarrollador tendría que especificar en los comentarios si se tratara de la información que debe convertirse en parte de la documentación pública.

Answer 2

Yo creo que esos tipos de condiciones de frontera, la mayoría sin duda pertenecen a la API.Sin embargo, me gustaría (y a menudo lo hacen) ir un paso más allá e indican LO que los valores null significa.Ya sea que indicar que se producirá una excepción, o de explicar lo que los resultados esperados son cuando el valor de límite se pasa.

Es difícil recordar siempre hacer esto, pero es una buena cosa para los usuarios de su clase.También es difícil de mantener si el contrato el método presenta cambios (como los valores null se cambia a no ser permitido)...usted tiene que ser diligente y también para actualizar los documentos cuando se cambia la semántica del método.

Answer 3

Pregunta 1

¿Usted ve a menudo en la documentación de la API (como en 'javadoc de las funciones públicas", por ejemplo) la descripción de los "límites de valor", así como el clásico de la documentación?

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 necesitas saber para seguridad de configuración de los parámetros y de forma segura a prueba el valor de retorno, sin embargo, casi nunca los veo ese tipo de información en la documentación de la API...

Si he utilizado una función no esté debidamente yo esperaría un RuntimeException arrojado por el método o una RuntimeException en otro (a veces muy lejos) parte del programa.

Comentarios como @param aReaderNameRegexp filter in order to ... (can be null or empty) me parece una forma de implementar Diseño por Contrato en un ser humano lengua dentro de Javadoc.

El uso de Javadoc para hacer cumplir Diseño por Contrato fue utilizado por iContract, ahora resucitado en JcontractS, que permiten especificar invariantes, precondiciones, postcondiciones, en más de una manera formalizada en comparación con el ser humano en el lenguaje.

Pregunta 3

Esto puede influir en el uso o no para activar o desactivar las excepciones.¿Qué te parece ?valor y límites de la API, pertenecen juntos o no ?

Lenguaje Java no tiene un Diseño por Contrato característica, así que usted puede ser tentado a utilizar Execption pero estoy de acuerdo con usted sobre el hecho de que usted tiene que ser consciente de Cuando a elegir facturado y sin excepciones.Probablemente podría utilizar sin marcar IllegalArgumentException, IllegalStateException, o usted podría utilizar la unidad de pruebas, pero el problema principal es cómo comunicar a otros programadores que dicho código es sobre el Diseño Por Contrato y debe ser considerado como un contrato antes de cambiar a la ligera.

Answer 4

Yo creo que lo hacen, y siempre han hecho comentarios en los archivos de encabezado (c++) arcordingly.

Además de la validez de entrada/salida y retorno de los comentarios, yo también tenga en cuenta que las excepciones son likly ser arrojado por la función (ya que a menudo se desea utilizar el valor devuelto por...bueno devolver un valor, prefiero las excepciones a través de 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

@Incendio Lancer:A la derecha!Me olvidé de la excepción, pero me gustaría ver a los mencionados, especialmente la desactivada 'en tiempo de ejecución' excepción de que este método público podría lanzar

@Mike Stone:

usted tiene que ser diligente y también para actualizar los documentos cuando se cambia la semántica del método.

Mmmm espero que la pública la documentación de la API es, al menos, actualizada cada vez que un cambio que afecta el contrato de la función -- se lleva a cabo.Si no, los de la API de documentaciones podría caer por completo.

Añadir alimentos a la suya pensamientos (y vaya con @Scott Dorman), me acabo de tropezar con el futuro de java7 anotaciones

¿Y eso qué significa ?Que ciertas "condiciones de frontera", en lugar de estar en la documentación, debería ser mejor en la API en sí, y utilizan de forma automática, en tiempo de compilación, con la correspondiente 'afirma' el código generado.

De esa manera, si un '@CheckForNull' es en el API, el escritor de la función podría no incluso documentando!Y si el cambio semántico, su API de reflejar ese cambio (como 'no más @CheckForNull", por ejemplo)

Ese tipo de enfoque sugiere que la documentación que, para las condiciones de frontera', es un bono extra en lugar de una práctica obligatoria.

Sin embargo, que no cubre los valores especiales del objeto de retorno de una función.Para que, una completa la documentación que se necesita.