Olá pessoal!

Dando continuidade à série Desenvolvendo para Android, irei falar sobre algumas maneiras para garantir a qualidade de software de seu projeto. Uma das mais efetivas técnicas é o uso de Annotations.

Annotations são marcações no código que definem certos comportamentos de métodos e variáveis. Por exemplo, você pode indicar que um parâmetro de seu método não pode ser null  utilizando a seguinte marcação:

    
public String meuMetodo(String nome, @NonNull Context contexto) {
    return null;
}

Com essa definição de método, se você fizer uma chamada em que context tem valor null, o Android Studio irá automaticamente mostrar um erro:

Ferramentas de análise estática de código como o Lint também utilizam as annotations para indicar erros.

РMas Felipe, eu sei que ṇo posso chamar o meu m̩todo desse jeito!

Sim! mas um programador que tenha que alterar seu código daqui a alguns meses pode não saber. Inclusive você pode não se lembrar 🙂

Adicionando a biblioteca de Annotations ao seu projeto

Para poder usar as Annotations é preciso adicionar a biblioteca que tem as definições necessárias. Para fazer isso, siga os seguintes passos:

1. Abrir o SDK Manager clicando no SDK Manager  na barra de ferramentas do Android Studio ou em Tools > Android > SDK Manager.
2. Selecionar a aba SDK Tools.
3. Expandir  Support Repository e selecionar Android Support Repository.
4. Clique OK.
5. Siga os passos do instalar de pacotes.
6. Adicionar a dependência support-annotations no build.gradle do seu projeto:

    dependencies { compile 'com.android.support:support-annotations:24.2.0' }

   (Utilize a versão que foi instalada nos passos anteriores).

Após seguir estes passos, basta começar a usar! A seguir veremos alguns dos principais tipo de annotations disponíveis.

Nullness Annotations

Já citadas neste post, as Nullness Annotations são usadas para indicar se um parâmetro, variável ou retorno de método pode ou não ser null. Alguns exemplos:

@NonNull
private String teste;

@Nullable
public String meuMetodo(String nome, @NonNull Context contexto) {
    return null;
}

Resource Annotations

Um problema comum em projetos grandes é a criação de métodos recebendo resources (strings, imagens ou layout): na lista de parâmetros, o resource será um int e é muito comum acontecer enganos ao chamar métodos como esse. Por exemplo, digamos que você tenha um método para mudar o texto de um TextView com um string resource declarado da seguinte forma:

public void mudarTexto(int texto) {
   ...   
}

É certo que em algum momento da vida de seu projeto alguém (talvez você mesmo!) irá chamar setText(30), querendo mostrar o inteiro 30 no TextView – e haverá um erro de compilação.

Isso poderá ser evitado usando a annotation @StringRes:

public void mudarTexto(@StringRes int texto) {
   ...   
}

Thread Annotations

Como já dito aqui no blog, existem algumas operações que precisam ser executadas em threads específicas. Também existem Annotations para isso que são muito úteis!

Se seu método for executar uma operação muito longa, que deve ser feita em background, você pode indicar isso utilizando a annotation @WorkerThread. Por outro lado, se seu método precisa atualizar a UI, você deve indicar isso usando @UiThread.

Value Constraint Annotations

Também é possível definir intervalo de valores possíveis para um determinado método. Por exemplo, se seu método espera receber valores entre 0 e 100, ele deve ser definido assim:

public void meuMetodo(@IntRange(from=0,to=100) int valor) { … }

Permission Annotations

A partir de Android 6 é necessário gerenciar algumas permissões específicas antes de utilizar alguns recursos e para isso as annotations também são bastante úteis! Se seu método necessita acessar o file system, por exemplo, a definição das annotations seria:

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.WRITE_EXTERNAL_STORAGE})
public void copiarArquivo(String destino, String origem) {
    ...
}

Conclusão

Neste post resumi algumas das mais comuns annotations, porém existem muitas outras também muito úteis, como @CheckResult e @CallSuper. Esta é uma ferramenta muito poderosa para garantir qualidade de código e que deve ser usada sempre que possível.

Para uma completa lista de annotations, visite a página dedicada a eles na documentação, na qual este post foi baseado: https://developer.android.com/studio/write/annotations.html

Um abraço e até a próxima!