Guia de estilo

Siga o guia de estilo do TypeScript do Google.

Migração para TypeScript e ES6

O Blockly foi originalmente escrito em ES5.1 em conformidade com uma versão anterior e atual do guia de estilo JavaScript do Google. O código recém-escrito precisa estar em conformidade com o guia de estilo atual e usar recursos da linguagem ES6, como let, const, class e atribuição de desestruturação, quando aplicável. O código atual pode ser atualizado ou deixado fora de conformidade. A equipe do Blockly tenta tomar a melhor decisão, levando em conta a consistência do código e a experiência dos usuários da biblioteca. Por exemplo, podemos optar por não renomear funções públicas que não estão mais em conformidade com o guia de estilo.

O que fazer

  • Use ferramentas de linting e formatação.
    • Usamos o eslint e temos um arquivo eslint.config.mjs configurado com regras para nosso estilo preferido.
    • Usamos o prettier para formatação automática.
    • Execute npm run lint para executar o linter e npm run format para executar o formatador.
  • Use espaços, não tabulações, para recuar.
  • Use pontos e vírgulas.
  • Use camelCase para variáveis e funções.
  • Use TitleCase para classes.
  • Use ALL_CAPS para constantes.
  • Use colchetes para todas as estruturas de controle.
    • Exceção: é possível omitir as chaves para instruções if de uma linha.
  • Use aspas simples (exceto ao gravar JSON).
  • Novas declarações de variáveis em loops for. Ou seja, sempre escreva for (const i = 0; ...) em vez de for (i = 0; ...).
    • Se você não fizer isso, aumenta o risco de que, após uma refatoração mais alta na função, a variável fique sem par e se torne global por surpresa.
  • Comece os comentários com letras maiúsculas e termine com pontos.
  • Crie problemas do GitHub com TODOs e os vincule usando TODO(#issueNumber).
  • Anote tudo com o TSDoc.

O que não fazer

  • Use tabulações para recuar.
  • Use sublinhados no final dos nomes de variáveis ou funções.
    • Alguns códigos anteriores usam sublinhados para propriedades ou funções privadas ou internas. Embora eles ainda possam existir, nenhum código novo pode ser adicionado seguindo essa convenção.
  • Use snake_case.
  • Use aspas duplas (exceto ao gravar JSON).
  • Use um TSDoc com formato incorreto.
    • O TSDoc é publicado automaticamente como parte da nossa documentação.
  • Escreva TODO (username).
    • Em vez disso, crie problemas do GitHub com TODOs e os vincule usando TODO(#issueNumber).
  • Use string.startsWith. Use Blockly.utils.string.startsWith.

TSDoc

A equipe do Blockly usa o TSDoc para anotar nosso código e gerar documentação. Esperamos que o TSDoc seja usado para todas as propriedades públicas de classes e para todas as funções exportadas.

Os comentários do TSDoc precisam começar com /** e terminar com */ para serem analisados corretamente.

Tipos

Os tipos são omitidos do TSDoc porque essas informações estão diretamente no código do TypeScript. Se você estiver editando um dos poucos arquivos JavaScript restantes, inclua anotações de tipo de acordo com a documentação do Closure Compiler.

Visibilidade

As funções ou propriedades que só podem ser acessadas na biblioteca do Blockly precisam ser anotadas com @internal. Isso impede que essas propriedades apareçam na documentação pública. Outros modificadores de visibilidade precisam ser colocados no código do TypeScript diretamente, não no TSDoc.

Propriedades

O TSDoc para propriedades precisa incluir uma descrição da propriedade. A descrição pode ser omitida para propriedades autoexplicativas.

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

Funções

As anotações para funções precisam incluir

  • Uma descrição da função
  • Uma tag @param por parâmetro, incluindo
    • Nome
    • Descrição
  • Uma tag @returns, se a função retornar um valor, com uma descrição do valor retornado.

As descrições podem ser omitidas para funções, parâmetros ou valores de retorno se eles forem autoexplicativos.

Exemplo:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}