Iara JavaScript Code Standards

Este padrão está sendo proposto para tornar possível:

1. O código JavaScript escrito por qualquer pessoa que siga este padrão seja compreendido e modificado por qualquer outra pessoa que também conheça este padrão sem qualquer problema;
2. A escrita de códigos JavaScript pequenos, que possam ser transferidos pela Internet gerando tão pouco tráfego quanto for possível;
3. Reunir boas práticas de codificação.

Como se pode notar facilmente, o ítem 2 parece conflitar com o ítem 3. Por isso, procuramos criar um meio termo entre os dois: um código bem-escrito e enxuto ao mesmo tempo. É neste ponto que reside o maior trabalho na elaboração deste padrão.

Indentação

1. Não se deve utilizar o demarcador de fim-de-código (ponto-e-vírgula) - como em Python -, exceto em dois casos especiais: o for quando usado em estilo C (dois comandos + uma expressão lógica) e o case quando tiver apenas um comando (pode-se usar ponto-e-vírgula para separar o comando do break). Como conseqüência, exceto nos casos explicitados, cada linha de código deverá apresentar no máximo um comando.
2. O delimitador de início de bloco (abre chaves) deve ser colocado ao final da estrutura que anuncia o bloco.
3. O delimitador de fim de bloco (fecha chaves) deve aparecer sozinho na linha e no mesmo nível de indentação da linha de código que abriu o bloco.
4. Não se deve utilizar espaços para indentação, apenas o caractere de tabulação (TAB).
5. O código começa alinhado à esquerda, não sendo necessário usar uma tabulação para o nível inicial do arquivo js.
6. Deve-se evitar o uso de linhas em branco no código. Quando necessárias para organização, certifique-se de não haver caracteres brancos (tabulações e espaços) na linha.
7. Blocos formados por uma só linha de código não precisarão de delimitadores de início e fim, somente da indentação.

function exemplo(){
for(i =0; i <10; i++)
alert('(' +i +') Este é o exemplo da identação')
alert('O exemplo da identação foi rodado ' +i +' vezes.')
}

Expressões

1. Qualquer operador (matemático, lógico, de atribuição) deve ser escrito com um espaço antes (entre o operador e o primeiro operando) e nenhum depois (deve estar unido ao segundo operando).
2. Variáveis incrementadas/decrementadas devem aparecer com o operador próximo a elas e separadas das demais da expressão (e demais operadores) por espaços (antes e depois, mas nunca acumulados com outros espaços que a expressão já traga próximo ao [in|de]cremento).
3. Expressões que demandem parênteses e chaves (tais como o if, o while ou mesmo o function) não apresentarão espaços na concatenação com parênteses e com chaves.
4. Encadeamentos de comandos separados por ponto-e-vírgula devem ter um espaço após cada ponto-e-vírgula.
5. Listas separadas por vírgula não devem apresentar espaços entre seus ítens e as vírgulas.

Esta é a forma proposta pelo padrão:

x =y *2 +3 /z

Aqui temos um caso se atribuição seletiva (lógica de circuitos):

aux =x ||y ||20

Outro exemplo maior:

function somaInteiros(a,b){
s ='A soma de ' +a +' com ' +b +' retornou '
while(b >0){
a++
b--
}
while(b <0){
a--
b++
}
return s +a +'.'
}

Note que o único espaço na primeira linha é o que se encontra depois de function.

Concatenação de strings (a e b são convertidos em strings automaticamente): colocar um espaço antes de cada sinal de concatenação.

Comentários

Evite colocar comentários no código. Tente fazer o código da maneira mais clara e auto-explicativa possível, colocando apenas comentário essenciais (como, por exemplo, o cabeçalho do arquivo, onde deve haver uma nota da licença de distribuição).

Nomenclatura

1. Nomes devem ser escritos em inglês, hábito considerado boa prática de programação. Um software não está preso a nenhuma cultura específica, não sendo cultural, mas uma forma internacional de resolver problemas. Por isso, escrever código com nomes em inglês não é falta de patriotismo;
2. Nomes são essencialmente em caracteres minúsculos, exceto nos casos tratados nos próximos ítens;
3. Nomes de classes começam sempre com a primeira letra em maiúsculo, a menos que seja uma classe de uma API. Neste caso, a API deve fornecer uma sub-string padrão, que deverá estar no início dos nomes de todas as classes da API. Esta sub-string pode ter letras maiúsculas e minúsculas livremente;
4. Sempre que o nome tiver mais que uma palavra o formando, cada palavra depois da primeira (que segue as regras apresentadas acima) deve ser unida ao restante, mudando-se apenas a primeira letra para maiúscula. Nunca utilizar sublinhados para essas uniões.
5. Nomes de atributos e métodos privados deverão ter um caractere “_” no início. Isso não os torna praticamente privados, mas conceitualmente, entre nós programadores. Uma solução similar é utilizada em Perl 5, que também não traz o conceito de método privado.
6. Deve-se evitar abreviações.

Exemplificando...

completeTable =new ADSTable()

O exemplo acima mostra um objeto completeTable sendo criado a partir da classe ADSTable.

O objeto é formado pelo nome “Complete Table”. Começando com minúscula por ser objeto, temos “complete Table”. Como é dito, cada palavra além da primeira deve ser unida ao resto, com a primeira letra em maiúscula. Por isso, “Table” se une ao “complete”, mantendo o “T” maiúsculo: “completeTable”.

A classe apresentada é a implementação de tabela de uma suposta API que adotou a sub-string "ADS" para definir suas classes. Por isso a classe tem esse nome: ”ADS” + “Table”.

Variáveis

1. Constitui-se uma boa prática de programação a declaração de variáveis. Entretanto, não havemos de declarar uma variável por questões de tamanho do arquivo gerado (var). Outras linguagens amplamente conhecidas não oferecem forma de se declarar variáveis (PHP 4) ou a oferecem como opcional (Perl 5 em modo normal). Portanto, consideraremos a declaração de uma variável como um hábito não-primordial para a boa apresentação do código, abolindo-a.
2. Uma variável deve ser sempre inicializada com um valor explícito, de uma outra variável ou retorno de uma função. Não se deve utilizar qualquer operador que aja sobre a variável sem que esta tenha recebido um valor inicial. Tal deve ser feito, preferencial mas não necessariamente, no início do bloco de código.
3. Vetores devem ser declarados com “[]” e não com “new Array()”.
4. Valores booleanos devem ser expressos como true ou false sempre que houver risco de valores numéricos causarem confusões. O ideal, entretanto, é que se utilize sempre 0 e 1, como em C.

Classes

1. Métodos devem ser declarados dentro da própria classe.
2. Herança deve ser feita através do processo de refazer o construtor a partir do construtor da classe mãe: cria-se um método make pela atribuição do construtor da classe mãe e invoca-se tal método logo em seguida.
3. No caso de herança múltipla, o método terá o mesmo nome, mas os dois passos serão seguidos mais de uma vez, sempre em par.

Vejamos, por exemplo, a classe ADSCode.

function ADSCode(s){
this.content =s ||''
this.add =function(s){
this.content +=s
}
this.obtain =function(){
return this.content
}
this.write =function(){
document.write(this.obtain())
}
}

É desta forma que todos os métodos são definidos dentro da classe. Veja add, obtain e write.

Agora suponha uma classe ADSParagraph, apenas para exemplificar (usando [p] para a tag de parágrafo, apenas para simplificar a edição aqui, na web).

function ADSParagraph(s){
this.make =ADSCode
this.make(s)
this.obtain =function(){
return '[p]' +this.content+ '[/p]'
}
}

As duas linhas que começam com this.make fazem com que o ADSParagraph herde todo o comportamento e estado inicial de ADSCode.

No exemplo, sobrescrevemos o método obtain, perdendo o herdado de ADSCode.