5.3. Ainda a documentação

O seguinte método serve para verificar se um inteiro tem um só algarismo:

xxxxxxxxxx
static boolean isSingleDigit(int x) {
    return x >= 0 && x < 10;
}

O método retorna false sempre que invocado com um valor negativo para o parâmetro, mesmo que esse valor tenha só um dígito (p.ex. -6). Não está preparado para trabalhar com valores negativos do parâmetro.

Em casos como este, os programadores que vão usar o método devem ser informados que o método não faz o que é esperado quando é invocado com valores negativos no parâmetro.

Fazemos isso adicionando alguns comentários à definição do método:

xxxxxxxxxx
/**
  * Um dado numero natural tem um soh algarismo?
  * @param x O numero a investigar
  * @return true se x tem um soh algarismo; false caso contrario
  * @requires x >= 0
  */
 static boolean isSingleDigit(int x) {
     return x < 10;
 }

Assim, os programadores que usem este método já ficam a saber que só o devem invocar com um valor positivo ou nulo para o parâmetro. E já que avisamos os potenciais invocadores deste método que o valor tem que ser positivo ou nulo, não precisamos de testar essa condição dentro do método (por isso só verificamos que é menor que 10).

Também podíamos ter feito assim:

xxxxxxxxxx
/**
  * Um dado numero tem um soh algarismo?
  * @param x O numero a investigar
  * @return true se x >=0 e x tem um soh algarismo; false caso contrario
  */
 static boolean isSingleDigit(int x) {
    return x >= 0 && x < 10;
 }

Neste caso o programador fica a saber que não há qualquer restrição sobre o valor do parâmetro (para além de ter que ser do tipo int) e que se for negativo ou tiver mais que um dígito o método retorna false.

Anterior: 5.2. Execução condicional

Seguinte: 5.4. Comparação de valores numéricos reais