a documentação da api e "valor limite":elas são iguais?

Question

Você costuma ver na documentação da API (como em 'o javadoc de funções públicas", por exemplo) a descrição do "valor limite" assim como o clássico de documentação ?

Nota: Eu não estou falando sobre comentários no código

Por "valor limite", eu quero dizer:

• um parâmetro pode suportar um valor nulo (ou uma Cadeia de caracteres vazia, ou...) ?
• faz um "valor de retorno" pode ser nulo ou é garantido para nunca ser nulo (ou pode ser "vazia", ou...) ?

Exemplo:

O que vejo frequentemente (sem ter acesso ao código-fonte) é:

/**
 * 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);

Que Eu gostaria de ver seria:

/**
 * 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);

Meu ponto é:

Quando eu uso uma biblioteca com um getReaderNames() função, eu muitas vezes não precisa nem ler a documentação da API para adivinhar o que ele faz.Mas eu preciso ter certeza como utilizar.

A minha única preocupação quando eu quiser usar esta função é:o que devo esperar no prazo de parâmetros e valores de retorno ?Que é tudo que eu preciso saber, com segurança, o programa de configuração meus parâmetros e segura de testar o valor de retorno, mas eu quase nunca vejo esse tipo de informação na documentação da API...

Editar:

Isso pode influenciar o uso ou não de marcado ou desmarcado exceções.

O que você acha ?limites de valor e API, eles pertencem ou não ?

Answer 1

Eu acho que eles pode pertencem juntos, mas não necessariamente tem para pertencem juntos.Em seu cenário, parece que faz sentido que os limites são documentados na forma em que aparecem na gerada a documentação da API e o intellisense (se a linguagem/IDE suporte a isso).

Eu acho que não dependem do idioma.Por exemplo, a Ada tem um tipo de dados nativo que é restrito "integer", onde você define uma variável de número inteiro e indicar explicitamente que apenas (e sempre) estar dentro de um determinado intervalo numérico.Nesse caso, o tipo de dados indica a restrição.Ele ainda deve ser visível e detectável através da documentação da API e do intellisense, mas não seria algo que um programador tem de especificar nos comentários.

No entanto, linguagens como o Java e o C# não tem esse tipo de restrição de número inteiro, de modo que o desenvolvedor teria que especificar nos comentários se fosse de informações que devem tornar-se parte da documentação pública.

Answer 2

Eu acho que esses tipos de condições de contorno definitivamente pertencem a API.No entanto, eu faria (e muitas vezes) ir um passo além e indicar QUE os valores null significa.Eu indicar irá lançar uma exceção, ou eu explicar o que os resultados esperados são quando o valor de limite é passado.

É difícil lembrar para sempre fazer isso, mas é uma coisa boa para os usuários de sua classe.Também é difícil manter-se o contrato o método não apresenta alterações (como valores nulos são alterados para não ser permitido)...você tem que ser diligente também para atualizar o google docs quando você alterar a semântica do método.

Answer 3

Questão 1

Você costuma ver na documentação da API (como em 'o javadoc de funções públicas", por exemplo) a descrição do "valor limite" assim como o clássico de documentação?

Quase nunca.

Questão 2

A minha única preocupação quando eu quiser usar esta função é:o que devo esperar no prazo de parâmetros e valores de retorno ?Que é tudo que eu preciso saber, com segurança, o programa de configuração meus parâmetros e segura de testar o valor de retorno, mas eu quase nunca vejo esse tipo de informação na documentação da API...

Se eu usei uma função corretamente, eu não seria de esperar uma RuntimeException acionada pelo método ou uma RuntimeException em um outro (às vezes muito), uma parte do programa.

Comentários como @param aReaderNameRegexp filter in order to ... (can be null or empty) parece-me uma forma de implementar Design por Contrato em um ser humano língua dentro de Javadoc.

Usando o Javadoc para impor Design por Contrato, foi usado por iContract, agora ressuscitado na JcontractS, que permitem que você especificar invariantes, pré-condições, pós-condições, no mais formalizados de maneira comparado com o ser humano idioma.

Questão 3

Isso pode influenciar o uso ou não para despachada ou não exceções.O que você acha ?limites de valor e API, eles pertencem ou não ?

A linguagem Java não tem um Projeto por Contrato de recurso, assim, você pode ser tentado a usar Execption mas eu concordo com você sobre o fato de que você tem que estar ciente sobre Quando escolher marcada e desmarcada exceções.Provavelmente você pode usar desmarcada IllegalArgumentException, IllegalStateException, ou você pode usar os testes de unidade, mas o grande problema é como se comunicar com outros programadores que, tal código é sobre Design Por Contrato e deve ser considerado como um contrato, antes de mudar-a levemente.

Answer 4

Eu acho que eles fazem, e tem sempre colocado comentários nos arquivos de cabeçalho c++) arcordingly.

Além válido de entrada/saída/retorno comentários, eu também nota que as exceções são likly a ser lançada pela função (já que muitas vezes eu quiser usar o valor de retorno para...bem, retornando um valor, eu prefiro exceções sobre os códigos de erro)

//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

@Incêndio Lancer:Direito!Esqueci-me de exceção, mas eu gostaria de vê-los mencionados, especialmente, a suposta 'tempo de execução' excepção de que este método público poderia jogar

@Mike Stone:

você tem que ser diligente também para atualizar o google docs quando você alterar a semântica do método.

Mmmm espero que o público a documentação da API é, no mínimo, atualizado sempre que uma mudança que afeta o contrato da função -- tem lugar.Se não, aqueles API documentações poderia ser cair.

Adicionar o alimento para o seu pensamento (e ir com @Scott Dorman), eu acabei de tropeçar em cima de o futuro da java7 anotações

O que isso significa ?Que certas "condições de contorno", ao invés de ser na documentação, deve ser melhor na própria API, e é utilizado automaticamente, em tempo de compilação, com as devidas 'afirmar' código gerado.

Dessa forma, se um '@CheckForNull' é na API, o escritor da função pode fugir nem mesmo documentá-lo!E se a mudança semântica, sua API irá refletir essa alteração (como 'não mais @CheckForNull' por exemplo)

Que tipo de abordagem sugere que a documentação, para "condições de contorno", é um bônus extra, em vez de uma prática obrigatória.

No entanto, o que não abrange os valores especiais do objeto de retorno de uma função.Para que, uma completo a documentação ainda é necessária.