Codding standards

Alfredo Goldman

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

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.

Porém....

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

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.

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

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.

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)

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.

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

Exemplos// indentação tradicionalsomeMethod(int anArg, Object anotherArg, String yetAnotherArg,

Object andStillAnother) { ... }

//Indentação com 8 espaços em certos casosprivate static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg,

Object andStillAnother) { ...

}

Exemplos

// indentação tradicionalif ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { //BAD WRAPS doSomethingAboutIt(); //difícil de achar }

// indentação propostaif ((condition1 && condition2) || (condition3 && condition4) ||!(condition5 && condition6)) { doSomethingAboutIt(); }

Em ifs use geralmente a regra de indentar com 8 espaços

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;

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...

ComentáriosIniciar 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 */ ...}

ComentáriosComentá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//}

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;

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... }

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... }}

Declarações

• Quantas por linha?– De preferência um por linha (help comments)

int level; // nivel de ruídoint size; // tamanho do buraco

– é melhor que:int level, size;

– Nunca deve se declarar dois tipos na mesma linhaint elemento, vetor[]; // errado!

– Pode-se alinhar declaraçõesint level; // indentation levelint size; // size of tableObject currentEntry; // currently selected table entry

Declarações

• Inicialização– Inicialize sempre as variáveis na hora da

declaração;• Exceção: variáveis que dependem de algum cálculo

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 especialfor (int i=0; i< max; i++) { ... }

• Não use o mesmo nome de variável em blocos internos

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 {}.

Declarações (classes e interfaces)

class Sample extends Object { int ivar1; int ivar2;

Sample(int i, int j) { ivar1 = i; ivar2 = j; }

int emptyMethod() {}

... }

Exemplo:

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.

Exemplos (if)

if (condition) {

statements;

}

if (condition) {

statements;

} else {

statements;

}

if (condition) {

statements;

} else if (condition) {

statements;

} else {

statements;

}

Exemplos (for)

for (initialization; condition; update) {

statements;}

for (initialization; condition; update);

// ao invés defor (init1, init2; condition; up1, up2){ statements;}

// fazerinit1;for(init2; condition; up1){ statements; up2;}

Exemplos (while, do while)

while (condition) {

statements;}

while (condition);

do { statement;} while (condition);

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}

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.

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");

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);

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 “_”

Dicas de programação

• Evite usar um objeto para acessar algo estáticoclassMethod(); //okAclass.classMethod(); //okanObject.classMethod(); //evitar

• Atribuições: uma em cada linhax = y = 0; // evitarx = 0;y = 0; // ok

d = (a = b + c) + r; //evitar

a = b + c; d = a + r; //ok

Dicas de programação

• Use parêntesesif (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

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.

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 */

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.

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.