Convenções básicas para Java

A linguagem Java é "Case Sensitive”, quer dizer, o interpretador diferencia palavras escritas com letras maiúsculas de letras minúsculas. Por exemplo são diferentes:

• OiMundo.java
• OIMUNDO.java
• OIMundo.java
• oiMundo.java

As convenções principais convenções utilizadas em Java são:

• Nomes de variáveis e métodos devem começar com letras minúsculas
• Nomes de classes iniciam com letras maiúsculas
• Nomes compostos (para classes, variáveis ou métodos) devemos utilizar letras maiúsculas para as iniciais das palavras
• As constantes devem ser escritas com letras maiúsculas
• Um nome de variável pode ser qualquer identificador válido composto por uma sequência de códigos Unicode de letras e dígitos começadas com uma letra ou cifrão "$" ou um underscore "_". Por convenção, os nomes devem ser sempre começados por letras.
• Também por convenção não se utiliza o cifrão apesar da compilador permitir seu uso.
• Os nomes das variáveis não podem ser palavras reservadas do Java.

Existem três formas de se inserir comentários em um código Java. São usados caracteres especiais para caracterizar cada um destes formatos:

• Comentário em uma linha: //
• Comentário em uma ou mais linhas: /*  */ 
• Comentário a ser inserido em documentação do código: /** */
• Quando é colocado imediatamente acima da declaração de um método, variável ou classe, indica que o comentário será incluído automaticamente em uma página HTML gerada pelo comando javadoc.

Vamos ver tudo isto com um exemplo:

1. /**
2. * @author Henrique
3. * @since 08/12/2011
4. * @param args é um array de strings que não é utilizado neste exemplo
5. * @ returns nada!
6. *
7. * Este é um programa completo em java que apresenta na linha de comando a mensagem
8. * Oi, Mundo!
9. *
10. * É uma variação do tradicional HelloWorld.java
11. */

1. public class OiMundo {  

    /*

       A linguagem Java tem por padrão a definição de um método main que indica

       onde o programa começa a ser executado, assim ao executar a linha de comando

       java OiMundo

       o interpretador Java irá procurar o método main() abaixo e por isto será

       apresentada a mensagem Oi, Mundo!

    */ 

1.    public static void main(String[] args) { // este programa não tem parâmetros de entrada
2.       String MENSAGEM = "Oi, Mundo!"; // veja como está escrito o nome da constante!
3. 
   
4.       System.out.println(MENSAGEM);  // mais informações no site da Oracle
5.       /*
6.          veja mais informações sobre System.out.println em
7.          http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/System.html
8.       */
9.    }  
10. }

Algumas das principais tags do javadoc estão relacionadas abaixo:

• @ author: Atribui uma classe ou método a um autor. 
• @ since: deve ser utilizada como referência para a data da escrita do código ou para o número da versão
• @ param: Parâmetro de um método 
• @ return: Retorno de um método 
• @ version: Versão de determinada classe ou método 
• @ see: string com indicação de referência adicional, tipo "Leia Também". Existe uma variação que permite a criação de um link html e referência para membros na mesma classe, para outra classe e até mesmo para outro pacote.
• @ throws ou @exception: Indica as exceções lançadas pelo método que está sendo documentado 
• @ deprecated: Indica que a API não deve ser utilizada apesar de ainda existir na classe

Mais informações sobre o Javadoc vale a pena ir à página da Oracle.

Veja a mesma classe escrita sem os comentários. Esta é a estrutura básica de uma classe que pode ser rodada em uma JVM:

1. 
   public class OiMundo {  

1.    public static void main(String[] args) {
2.       String MENSAGEM = "Oi, Mundo!"; 
3.       System.out.println(MENSAGEM);  
4.    }  
5. }

Se quiser testá-la, entre no notepad++ (ou em outro editor de textos). Copie e cole o texto em azul acima. Grave o arquivo como OiMundo.java (note as letras maiúsculas e minúsculas - o Java é case sensitive). Compile com o javac e rode com o java (como na tela acima).