Adotando padrões ao codificar em JavaScript

A algum tempo atras, JavaScript era considerado uma linguagem de terceira categoria, "vagabunda" que só servia para validar formulários. Porém hoje, apesar de ainda existirem, já são muito poucos os que acham isto, principalmente com o avanço da linguagem e seus usos. Ao contrário do que pensava-se antigamente, JavaScript não apenas valida formulários mas sua utilização vai desde a requisição assincrona de dados de servidor, API's de uma infinidade de serviços até o controle de vídeo e audio passando pelo desenvolvimento de jogos e aplicações para mobile.

Mas o que talvez tenha dado fama ruim no passado foi, como diriamos, uma permissividade muito grande da linguagem, fazendo com que programadores que não se preocupassem com desempenho ou boas práticas fizessem "o diabo" com a mesma.

Partindo deste pressuposto, vamos fazer as coisas bem feitas? O início de tudo é adotar padrões para que seu código possa ser lido de maneira clara e limpa, facilitando a manutenção e as melhorias.

Iniciamos então pela padronização da nomenclatura

Construtores

Adotamos a primeira letra sempre em maiusculo
Exemplo:
var joao = new Pessoa();

Funções e métodos

Adotamos a primeira letra em minúsculo e a primeira letra das palavras seguintes em maiúsculo, sem espaço ou traços entre palavras. Este formato é comumente chamado de "camelo" ou Camel Case.
Exemplo:

function meuMetodoTeste() {...}
function minhaFuncaoTeste() {...}

Variáveis

Adotamos todas as letras em minúsculo, porém as palavras são separadas por um underscore.

Exemplo:

var minha_variavel_numero = 1;

Constantes

Adotamos todas as letras maiúsculas, porém as palavras são separadas por um underscore.

Exemplo

var TAMANHO_MAXIMO = 10;
var PI = 3.14;

Comentários e documentação

Assim como a linguagem em si, os comentários e documentação também devem seguir alguns padrões.

São muitos os motivo para se documentar seu código indo desde a simples organização até a geração de documentação automaticamente.

Imagine uma situação em que você tem um problema complexo e depois de muito tempo de estudo consegue resolvê-lo. No momento em que você termina de codificar e testar a solução está tudo bem, você sabe exatamente o que resolveu, os parâmetros envolvidos e etc. mas será que daqui a duas semanas, um mês ou um ano você vai lembrar qual era o problema e como o resolveu? Muito provavelmente não. Eis ai uma situação em que a correta documentação, dentro de um padrão bem estabelecido por você, vai lhe poupar muitas horas de re-análise no caso de necessitar efetuar alguma atualização, melhorar o código ou até mesmo copiar a solução para outro problema semelhante.

Chovendo no molhado

//Faz um loop para ler a array conteudo
for(item in conteudo)
{
     console.log(item)
}

Você acredita que o comentário acima traz mesmo alguma informação relevante?
No meu ponto de vista apenas diz o óbvio, o que não nos ajuda em nada na compreensão do código. Este é um exemplo do que deve ser evitado. Comentários óbvios não vão nos ajudar em nada.


//Lê array vinda de json de notícias
for(item in conteudo)
{
     console.log(item)
}


Se você precisar ler 1000 linhas de código para saber o que é a variável conteudo o comentário acima será muito útil.


Que padrão seguir?

O mais importante dos padrões não é necessáriamente adotar este ou aquele mas, ao adotar qualquer que seja, procurar segui-lo sempre.

Um bom padrão de documentação é o que segue abaixo:

/**
* Descrição da função, classe(construtor) ou  método
*
* @param  {String} nome_do_parametro descrição do primeiro parâmetro
* @param  {Number} nome_do_outro_parametro descrição do segundo parâmetro
* @return   {String}   descrição do tipo de retorno da função ou método
*/
var Construtor = function()
{
  //Código....
}

Temos então um padrão do tipo * @chave valor que deixa claro para quem lê o código os parâmetros de entrada e a saída. Mas não são @param e @return as únicas chaves possíveis de se utilizar. Abaixo descrevo várias chaves comumente utilizadas dentro de uma documentação:

@namespace
É a referência global que contém um objeto.
Utilizado quando se cria um objeto em branco. Ex: var APP = {}
Neste caso teríamos @namespace APP

@class
Nome da Classe

@method
Nome do Método

@param
Lista de argumentos com tipo, nome e descrição

@return
Retorno da função ou método  com tipo e descrição (não possui nome)

@constructor
Indica que a classe em que aparece é um construtor

@author
Auto Explicativo

@version
Auto Explicativo

O valor entre chaves {tipo} indica qual o tipo de dados de entrada para cada parâmetro e saída. Podemos ter os tipos {string}, {number}, {boolean}, {array}, {object} e {none}. Este último pode ser utilizado, por exemplo, para indicar que uma função ou método não possuem retorno. Logo depois temos o nome da variável e na sequência sua descrição.