Udacity Nanodegree Desenvolvedor Android - Orientações de Estilos Java

Não Ignore Excessões

Você deve lidar com todas as Exceções no seu código de alguma forma com princípios. A manipulação específica varia de acordo com o caso.

Não Recomendado:

void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) { }
}

Recomendado:

Jogue a exceção até o chamador de seu método.

void setServerPort(String value) throws NumberFormatException {
    serverPort = Integer.parseInt(value);
}

Jogando uma nova excessão é o jeito apropriado para seu nível de abstração.

void setServerPort(String value) throws ConfigurationException {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        throw new ConfigurationException("Port " + value + " is not valid.");
    }
}

Manuseie o erro graciosamente e substitua um valor apropriado no bloco catch {}.

/** Definir a porta. Se o valor não for um número válido, substituir por 80. */
void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        serverPort = 80;  // default port for server 
    }
}

Não pegue Exceções Genéricas

É inapropriado capturar Excepção genérica ou Throwable, preferivelmente não Throwable, porque inclui exceções do erro também. É muito perigoso. Isso significa que exceções que você nunca esperava (incluindo RuntimeExceptions como ClassCastException) acabam sendo pegas no tratamento de erros no nível do aplicativo. Obscure as propriedades de processamento de falhas do seu código.

Não Recomendado:

try {
    someComplicatedIOFunction();        // may throw IOException 
    someComplicatedParsingFunction();   // may throw ParsingException
    someComplicatedSecurityFunction();  // may throw SecurityException
    // phew, made it all the way
} catch (Exception e) {                 // I'll just catch all exceptions
    handleError();                      // with one generic handler!
}

Recomendado:

• Podem haver determinados códigos de teste e códigos de nível superior onde você deseja capturar todos os tipos de erros (para evitar que eles apareçam em uma interface do usuário ou para manter um trabalho em lote em execução). Nesse caso, você pode pegar genérico Exception (ou Throwable) e lidar com o erro adequadamente.
• Pegue cada exceção separadamente como blocos de captura separados após uma única tentativa. Cuidado para não repetir código demais nos blocos catch.
• Refactore seu código para ter um tratamento de erros mais refinado, com vários blocos de tentativa. Dividir o IO a partir da análise e tratar erros separadamente em cada caso.
• Jogue novamente a exceção. Muitas vezes você não precisa pegar a exceção neste nível de qualquer maneira, basta deixar o método jogá-lo.

Qualificar Totalmente as Importações

Não Recomendado:

import foo.*;

Recomendado:

import foo.Bar;

Isso torna óbvio quais classes são realmente usadas. Torna o código Android mais legível para os mantenedores.

Não Use Finalizadores

Finalizadores são uma maneira de ter um pedaço de código executado quando um objeto é coleta de lixo.

Na maioria dos casos, você pode fazer o que você precisa de um finalizador com um bom tratamento de excessão. Se você precisar absolutamente dele, defina um método close() (ou similar), imprima uma mensagem curta de log do finalizador e documente exatamente quando esse método precisa ser chamado.

Comentários Padrão Javadoc

Recomendado:

Cada arquivo deve ter uma declaração de direitos autorais na parte superior. Em seguida, uma declaração de pacote e instruções de importação devem seguir. Cada bloco é separado por uma linha em branco. Finalmente, há a declaração de classe ou interface. Nos comentários Javadoc, descreva o que a classe ou interface faz.

/*
 * Copyright (C) 2013 The Android Open Source Project
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

/**
 * Does X and Y and provides an abstraction for Z.
 */

public class Foo {
    ...
}

Cada classe e método público não trivial que você escrever deve conter um comentário Javadoc com pelo menos uma frase descrevendo o que a classe ou método faz. Certifique-se de começar com um verbo descritivo na terceira pessoa.

/** Retorna a raiz quadrada positiva corretamente arredondada de um valor double. */
static double sqrt(double a) {
    ...
}

OU

/**
 * Constructs a new String by converting the specified array of 
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}

Você não precisa escrever o Javadoc para métodos triviais de get e set.

O Android não impõe atualmente um estilo específico para escrever comentários Javadoc, mas você deve seguir as instruções em Como escrever comentários Doc para a ferramenta Javadoc (conteúdo em Inglês).

Limite o Escopo da Variável

O escopo das variáveis locais deve ser mantido no mínimo. Isso aumenta a legibilidade e a capacidade de manutenção do código e reduz a probabilidade de erros.

Cada variável deve ser declarada no bloco mais interno que incluir todas as utilizações da variável.

Cada declaração de variável local deve conter um inicializador (se você não tiver informações suficientes para inicializar, você pode adiar isso).

As variáveis de loop devem ser declaradas na instrução for, a menos que exista uma razão convincente para fazer o contrário:

for (int i = 0; i < n; i++) {
    doSomething(i);
}

Ordene Declarações de Import

A ordem das declarações de importação é:

1. Imports do Android
2. Imports de terceiros (com, junit, net, org)
3. Imports java e javax

Para corresponder exatamente às configurações IDE, as importações devem ser:

• Alfabética dentro de cada agrupamento, com letras maiúsculas antes de letras minúsculas (por exemplo, Z antes de a).
• Deve haver uma linha em branco entre cada grande grupo (android, com, junit, net, org, java, javax).

As importações estáticas podem ser um pouco complicadas. Pode ser intercalado com as importações restantes ou abaixo de todas as outras importações. Deixamos isso a julgamento. Seja consistente.

Use Espaços para Indentação

Usamos 4 espaços para blocos. Nunca usamos guias. Em caso de dúvida, seja consistente com o código ao seu redor.

Usamos 8 recuos de espaço para envoltórios de linha, incluindo chamadas de função e atribuições.

Não Recomendado:

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

Recomendado:

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

Siga as Convenções de Nomenclatura de Campos

• Os nomes de campos não-públicos, não estáticos começam com m.
• Os nomes de campos estáticos começam com s.
• Outros campos começam com uma letra minúscula.
• Campos públicos, finais e estáticos (constantes) são TODAS_MAIÚSCULAS_COM_UNDERSCORES.

Recomendado:

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

Usar Estilo de Chaves Padrão

Chaves não tem sua própria linha; Elas começam na mesma linha que o código antes dela.

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

Exigimos chaves em torno das declarações para um condicional. Exceto, se todo condicional ( condição e o corpo) se encaixam em uma linha, você pode (embora não seja obrigado) colocar tudo em uma linha.

Não Recomendado:

if (condition)
    body();  // bad!

Recomendado:

if (condition) {
    body();
}

and

if (condition) body();

Use Comentários TODO

Use comentários TODO para o código que é temporário, uma solução de curto prazo, ou bom o suficiente, mas não perfeito.

TODOs devem incluir a string TODO totalmente em maiúscula, seguido de dois pontos:

// TODO: Remove this code after the UrlTable2 has been checked in.

and

// TODO: Change this to use a flag instead of a constant.

If your TODO is of the form "At a future date do something" make sure that you either include a very specific date ("Fix by November 2005") or a very specific event ("Remove this code after all production mixers understand protocol V7.").

Trate Acrônimos como Palavras

Trate siglas e abreviações como palavras em variáveis de nomeação, métodos e classes. Desta forma, os nomes são muito mais legíveis.

Não Recomendado:

XMLHTTPRequest
getCustomerID();
class HTML{}
String URL;
long ID; 

Recomendado:

XmlHttpRequest
getCustomerId();
class Html{}
String url;
long id; 

Evite Usar Números Mágicos

Um número mágico é um valor codificado que pode mudar em uma etapa posterior, mas que pode ser, portanto, difícil de atualizar.

Não Recomendado:

public class Foo {
    public void setPin(String pin) {
         // don't do this
         if (pin.length() > 4) {
              throw new InvalidArgumentException("pin");
         }
    }
}

Certifique-se de refatorar o código acima definindo uma constante numérica para armazenar o valor do tamanho do pino. NOTA: Defina constantes numéricas como final

Recomendado:

public class Foo {
    public static final int MAX_PIN_SIZE = 4;
    public void setPin(String pin) {
         if (pin.length() > MAX_PIN_SIZE) {
              throw new InvalidArgumentException("pin");
         }
    }
}

Usar Anotações Padrão Java

As anotações devem preceder outros modificadores para o mesmo elemento de linguagem. As anotações de marcador simples (por exemplo, @Override) podem ser listadas na mesma linha com o elemento de idioma. Se houver várias anotações ou anotações parametrizadas, elas devem ser listadas uma por linha em ordem alfabética.

As práticas padrão do Android para as três anotações predefinidas em Java são:

• @Deprecated: A anotação @Deprecated deve ser usada sempre que o uso do elemento anotado é desencorajado. Se você usar a anotação @Deprecated, você deve também incluir a tag Javadoc @deprecated (e vice-versa) e deve indicar uma implementação alternativa.
• @Override: A anotação @Override deve ser usada sempre que um método substituir a declaração ou implementação de uma super-classe.
• @SuppressWarnings: A anotação @SuppressWarnings só pode ser utilizada em circunstâncias em que é impossível eliminar um aviso. Quando uma anotação @SuppressWarnings é necessária, deve ser prefixada comum comentário TODO que explica a condição "impossível de eliminar". Por exemplo:

  // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
  @SuppressWarnings("generic-cast")
  List<String> blix = Utility.rotate(blax);

Limitação de Log

Enquanto o Log é necessário, ele tem um impacto significativamente negativo sobre o desempenho e rapidamente perde sua utilidade se não for mantido razoavelmente conciso.

Definir Campos em Locais Padrão

Os campos devem ser definidos na parte superior do arquivo ou imediatamente antes dos métodos que os utilizam.

Escreva Métodos Curtos

Os métodos devem ser mantidos pequenos e focados. Embora não haja limite rígido no comprimento do método, pense se as definições de métodos que vão acima de 40 linhas podem ser quebradas sem prejudicar a estrutura do programa.

Limite o Tamanho da Lina

Cada linha de texto no seu código deve ter no máximo 100 caracteres.

Exceção:

Se uma linha de comentário contém um comando de exemplo ou um URL literal com mais de 100 caracteres, essa linha pode ter mais de 100 caracteres para facilidade de recortar e colar.

Linhas de importação podem ultrapassar o limite porque os humanos raramente os vêem. Isso também simplifica a escrita da ferramenta.