Comentários (Código Limpo: Que Bruxaria é Essa?!?! - Parte Final)

Comente apenas códigos com lógica de negócio complexa

Comentários são um pedido de desculpas, não uma necessidade. Um bom código se documenta por si só na maioria das vezes.

Não é recomendável:

function hashIt(data) {
  // The hash
  let hash = 0;

  // Length of string
  const length = data.length;

  // Loop through every character in data
  for (let i = 0; i < length; i++) {
    // Get character code.
    const char = data.charCodeAt(i);
    // Make the hash
    hash = (hash << 5) - hash + char;
    // Convert to 32-bit integer
    hash &= hash;
  }
}

É recomendável:

function hashIt(data) {
  let hash = 0;
  const length = data.length;

  for (let i = 0; i < length; i++) {
    const char = data.charCodeAt(i);
    hash = (hash << 5) - hash + char;

    // Convert to 32-bit integer
    hash &= hash;
  }
}

Não deixe código comentado na sua base de códigos

Controle de versão existe por um motivo. Deixe o código antigo no seu histórico.

Não é recomendável:

doStuff();
// doOtherStuff();
// doSomeMoreStuff();
// doSoMuchStuff();

É recomendável:

doStuff();

Não tenha diários de comentários

Lembre-se, use controle de versão! Não há necessidade de código morto, código comentado e muito menos diário de comentários. Use git log para acessar o histórico!

Não é recomendável:

/**
 * 2016-12-20: Removed monads, didn't understand them (RM)
 * 2016-10-01: Improved using special monads (JP)
 * 2016-02-03: Removed type-checking (LI)
 * 2015-03-14: Added combine with type-checking (JR)
 */
function combine(a, b) {
  return a + b;
}

É recomendável:

function combine(a, b) {
  return a + b;
}

Evite marcadores de posição

Marcadores de posição só deixam sujeira. Deixe as funções e nomes de variáveis com o alinhamento e formatação adequados, dando estrutura visual ao seu código.

Não é recomendável:

////////////////////////////////////////////////////////////////////////////////
// Scope Model Instantiation
////////////////////////////////////////////////////////////////////////////////
$scope.model = {
  menu: "foo",
  nav: "bar"
};

////////////////////////////////////////////////////////////////////////////////
// Action setup
////////////////////////////////////////////////////////////////////////////////
const actions = function() {
  // ...
};

É recomendável:

$scope.model = {
  menu: "foo",
  nav: "bar"
};

const actions = function() {
  // ...
};

E aí? Gostaram? Até a próxima anotação! 😊