Guia de estilo do Blockly

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 mais antiga, versão atual do estilo JavaScript do Google guia. 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 existente pode ser atualizado ou não estar em conformidade. A equipe do Blockly tenta tomar a melhor decisão considerando a consistência do código e as experiência dos usuários da biblioteca. Por exemplo, podemos optar por não renomear funções públicas que não estejam mais em conformidade com o guia de estilo.

O que fazer

• Use ferramentas de linting e formatação.
  • Usamos eslint e temos um .eslintrc.js arquivo configurado com regras para nosso estilo preferido.
  • Usamos a opção mais bonita para a formatação automática.
  • Execute npm run lint para executar o lint 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 as turmas.
• Use ALL_CAPS para constantes.
• Usar chaves para todas as estruturas de controle.
  • Exceção: você pode omitir as chaves para instruções if de linha única.
• Use aspas simples (exceto ao escrever JSON).
• Declare novamente as variáveis em repetições for. Ou seja, sempre escreva for (const i = 0; ...) em vez de for (i = 0; ...).
  • Não fazer isso aumenta o risco de que, após uma refatoração mais acima no função a variável ficará órfã e se tornará uma surpresa global.
• Iniciar os comentários com letras maiúsculas e terminar com pontos finais.
• Criar problemas do GitHub com tarefas e vinculá-las usando TODO(#issueNumber).
• Anote tudo com o TSDoc.

O que não fazer

• Recuo com guias.
• Use sublinhados no final dos nomes de variáveis ou funções.
  • Alguns códigos anteriores usam sublinhados para propriedades privadas ou internas ou . Embora eles possam continuar a existir, nenhum código novo deve ser adicionados seguindo essa convenção.
• Use snake_case.
• Use aspas duplas (exceto ao escrever 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 vincule-os 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 tenha todas as propriedades públicas das 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 classe Closure Compiler Documentação.

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. Outra visibilidade modificadores deve ser colocado diretamente no código do TypeScript, não no TSDoc.

Propriedades

O TSDoc de propriedades deve incluir uma descrição da propriedade. O description pode ser omitido 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 vai retornar um valor com uma descrição dele.

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