Codding standards

1. Codding standards Alfredo Goldman

2. Motivação • Quem escreveu não deve ser o único a poder ler o código • Ainda mais em um sistema OO • Regras simples (muito simples) ajudam • Algumas são bem óbvias... • Criar um padrão (consensual) • Em parte independente da linguagem

3. Mais razões • 80% do tempo de desenvolvimento é para manutenção; • Quase nenhum software é mantido apenas pelo primeiro desenvolvedor; • Convenções de código melhoram a legibilidade do código; • Se o código fonte é fornecido com o sistema, ele deve estar bem apresentado.

4. Porém.... • Para que codding standards funcionem todos os desenvolvedores devem estar de acordo com a convenção, TODOS.

5. Resumo (baseado no padrão da sun) • Nome dos arquivos; • Estrutura dos arquivos; • Indentação; • Comentários; • Declarações; • Comandos; • Espaços em branco; • Convenção para nomes; • Práticas (simples e saudáveis) de programação.

6. Nome dos Arquivos • Mesmo que a linguagem não exija, use sufixos claros • ex. .java, .c, .cpp, .txt • Use makefiles com nomes padrão: • ex: xpmakefile • Sempre tenha no diretório um README • este arquivo deve conter um resumo do conteúdo do diretório

7. Estrutura dos Arquivos • Arquivos contém seções que devem ser separadas por linhas em branco e por comentários antes de cada seção; • Deve se evitar arquivos com mais de 2000 linhas.

8. Classes/Interfaces • Começam com um comentário do tipo /**...*/ • O comando class, ou interface • Comentários sobre a implementação /*...*/ • Variáveis estáticas (em ordem de acesso) • Variáveis da classe (public, protected, friendly,private) • Construtores • Métodos (agrupados por funcionalidade e não por escopo)

9. Indentação (é bem importante) • Use apenas espaços (tabs = 4 espaços) • Evite linhas com mais de 80 caracteres • Regras para quebra de linha: • quebra após vírgula; • quebra antes de operador; • quebra no maior nível possível; • alinhar a quebra com o começo da expressão do mesmo nível; • Se ficar feio, indentar com 8 espaços.

10. Exemplos someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3)); longName1 = longName2 * (longName3 + longName4 - longName5) + 4 *longName6; // melhor longName1 = longName2 * (longName3 + longName4 -longName5) + 4 *longName6; // pior

11. Exemplos // indentação tradicional someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... } //Indentação com 8 espaços em certos casos private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) { ... }

12. Exemplos Em ifs use geralmente a regra de indentar com 8 espaços // indentação tradicional if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //BAD WRAPS doSomethingAboutIt(); //difícil de achar } // indentação proposta if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); }

13. Exemplos (cont.) //Ou esta if ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); } // expressões ternárias alpha = (aLongBooleanExpression) ? beta : gamma; //ou alpha = (aLongBooleanExpression) ? beta : gamma; //ou alpha = (aLongBooleanExpression) ? beta : gamma;

14. Comentários linhas gerais • Dois tipos de comentários (da implementação e da documentação) • Linguagens modernas tem formas específicas • use-as ! • Não adicione comentários redundantes • O excesso de comentários reflete código mal escrito • pense em rescrever o trecho...

15. Comentários Iniciar sempre o bloco comentário com uma linha em branco: /* * Here is a block comment. */ Comentários de uma única linha devem ser precedidos por uma linha em branco: if (condicao) { /* Comentário da condição */ ... }

16. Comentários Comentários muito curtos podem estar na mesma linha. Se existem vários os mesmo devem estar alinhados. if (a==2) { return TRUE; /* um caso especial */ } else { return isPrime(a); /* funciona para a ímpar */ } Comentários com // também podem ser usados: if (foo>2) { // comentário de linha ... } else { return false; // comentário de fim de linha } //if (outracond==1) { // return true; // trecho de codigo comentado //}

17. Comentários (em java usar javadoc) Um exemplo: /** * Class description goes here. * * @version 1.82 18 Mar 1999 * @author Firstname Lastname */ public class Blah extends SomeClass { /* A class implementation comment can go here. */ /** classVar1 documentation comment */ public static int classVar1; /** * classVar2 documentation comment that happens to be * more than one line long */ private static Object classVar2;

18. Comentários (em java usar javadoc) cont. /** instanceVar1 documentation comment */ public Object instanceVar1; /** instanceVar2 documentation comment */ protected int instanceVar2; /** instanceVar3 documentation comment */ private Object[] instanceVar3; /** * ...constructor Blah documentation comment... */ public Blah() { // ...implementation goes here... }

19. Comentários (em java usar javadoc) cont. /** * ...method doSomething documentation comment... */ public void doSomething() { // ...implementation goes here... } /** * ...method doSomethingElse documentation comment... * @param someParam description */ public void doSomethingElse(Object someParam) { // ...implementation goes here... } }

20. Declarações • Quantas por linha? • De preferência um por linha (help comments) int level; // nivel de ruído int size; // tamanho do buraco • é melhor que: int level, size; • Nunca deve se declarar dois tipos na mesma linha int elemento, vetor[]; // errado! • Pode-se alinhar declarações int level; // indentation level int size; // size of table Object currentEntry; // currently selected table entry

21. Declarações • Inicialização • Inicialize sempre as variáveis na hora da declaração; • Exceção: variáveis que dependem de algum cálculo

22. Declarações • Localização • Sempre no início de blocos; • mas podem ser declaradas no início do método. void myMethod() { int int1 = 0; // beginning of method block if (condition) { int int2 = 0; // beginning of "if" block ... } } // o for é um caso especial for (int i=0; i< max; i++) { ... } Não use o mesmo nome de variável em blocos internos

23. Declarações (classes e interfaces) • Não dê espaço entre antes do “)”; • O “{” deve ficar no final da linha • O “}” deve estar alinhado com o comando; • Métodos devem estar separados por uma linha em branco; • Comandos vazios podem ser dados por {}.

24. Declarações (classes e interfaces) Exemplo: class Sample extends Object { int ivar1; int ivar2; Sample(int i, int j) { ivar1 = i; ivar2 = j; } int emptyMethod() {} ... }

25. Comandos • Colocar um comando por linha; • Em um bloco indentar sempre; • Colocar { no final da linha onde começa o bloco e } alinhado com o início desta.; • Use {} mesmo quando os blocos tiverem apenas um comando.

26. Exemplos (if) if (condition) { statements; } if (condition) { statements; } else { statements; } if (condition) { statements; } else if (condition) { statements; } else { statements; }

27. Exemplos (for) for (initialization; condition; update) { statements; } for (initialization; condition; update); // ao invés de for (init1, init2; condition; up1, up2){ statements; } // fazer init1; for(init2; condition; up1){ statements; up2; }

28. Exemplos (while, do while) while (condition) { statements; } while (condition); do { statement; } while (condition);

29. Exemplos (switch) switch (condition) { case ABC: statements; /* se não houver break, coloque comentário */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; // é redundante mas pode evitar erros futuros }

30. Espaços em Branco • Use linhas em branco para a separação lógica • duas para • separar seções do mesmo arquivo; • entre definições de classes e interfaces. • uma para • entre métodos; • dentro de um método entre as variáveis e o 1º comando; • antes de comentários (de bloco, ou linha); • entre as seções lógicas de um método.

31. Espaços em branco • Entre keywords e parênteses; while (true) { ... }// assim fica fácil visualizar métodos (sem espaço) • Após vírgulas em listas de argumentos; • Antes e depois de operadores binários a += c + d; a = (a + b) / (c * d); while (d++ = s++) { n++; // mas não para operadores unários } printSize("size is " + foo + "\n");

32. Espaços em branco • Entre os comandos de um for; for (expr1; expr2; expr3){ ... } • Após operações de cast myMethod((byte) aNum, (Object) x); myMethod((int) (cp+5), ((int) (i + 3)) + 1);

33. Nomenclatura • Packages • pode-se usar domínio + subdiretórios; • Classes e Interfaces • Primeira letra de cada palavra maiúscula; • Métodos • verbos, com 1ª letra minúscula e letras de cada palavra maiúsculas; • Variáveis • 1ª letra minúscula, pequenos, se temp. ok i, j, k. • Constantes • Tudo maiúsculo separado por “_”

34. Dicas de programação • Evite usar um objeto para acessar algo estático classMethod(); //ok Aclass.classMethod(); //ok anObject.classMethod(); //evitar • Atribuições: uma em cada linha x = y = 0; // evitar x = 0; y = 0; // ok d = (a = b + c) + r; //evitar a = b + c; d = a + r; //ok

35. Dicas de programação • Use parênteses if (a == b && c == d) //evitar if ((a == b) && (c == d)) //ok • Use operadores ternários (em certas situações) if (cond) { return x; } return y; return (cond ? X : y); Coloque o comentário XXX se há algo com problema e FIXME onde existem bugs

36. Dicas de Programação • Se você tem métodos com mais de 80 linhas, provavelmente o código não está bem organizado; • Se seus arquivos tem mais de 500 linhas veja o item anterior; • Não use variáveis globais.

37. Padronizar o cabeçalho /* * Nome do Arquivo: Teste.java * * Descrição: Este é um arquivo que serve para testar a * classe Cliente.Java * * Projeto: PDAs de venda; * Autor: Eu, tu e eles */

38. Dicas gerais • Sempre terminar o arquivo com uma linha em branco; • Antes de colocar um comentário para alguém no código, envie-lhe um e-mail; • Sempre faça uma mensagem de “uso”; • Sempre termine os #endif com um comentário correspondente ao #if; • Coloque /* */ entre o #include e o nome do arquivo (visual C++); • Defina constantes com um prefixo ligado ao projeto: ex: XP_MAX_CLIENTE; • Proteja headers de inclusões múltiplas: • Nunca faça o cast de um ponteiro para um inteiro (use long); • Sempre que usar arquivos, verifique se não ocorreram erros de abertura, escrita, etc.

39. Caso particular • Quais padrões de código seriam úteis a XP ? • Os programas atuais respeitam estes padrões ? • Na prática, verificar que respeitar os padrões não é tão difícil.