O estilo de código do Total.js: nomes, ficheiros, CSS, SQL e componentes

Os projetos Total.js partilham um estilo, e isso é uma força: abre qualquer um e sabe onde estão as coisas e como estão escritas. Esta página reúne num só lugar as convenções das Total.js guidelines (a revisão consultada está registada em ai-sources.json). Siga primeiro o estilo do projeto em que trabalha; estas são as regras por omissão para código novo. Para o lado da framework, leia as convenções do Total.js 5 para assistentes de código.

JavaScript

• Ficheiros: nomes em minúsculas, com hífenes em vez de sublinhados (user-profile.js).
• Formato: tabulações (largura 4), sem espaços a mais e ponto e vírgula no fim de cada instrução.
• Cadeias: aspas simples para as cadeias curtas.
• Variáveis: use var ou let dentro dos métodos e guarde const para o topo de um módulo.
• Ciclos: onde couber, prefere-se um for clássico a forEach().
• Dependências: mantenha-as no mínimo e siga o código que já existe.

Nomes que viajam entre projetos

Use o mesmo nome para a mesma coisa em todo o lado, para que o código possa passar de um projeto para outro e ler-se de relance:

Nome	Uso
id, name, value, email	o identificador, o nome, o valor e o e-mail habituais
items or arr, item	uma lista e um dos seus elementos
tmp	um valor temporário
dtcreated, dtupdated	datas de criação e de atualização

Os esquemas usam um nome no plural que começa por maiúscula (Contacts), e os identificadores criam-se com UID().

Usar o require()

No topo de um módulo use const e comece o nome da variável por maiúscula: const Fs = require('fs');.

CSS

• Nomes de ficheiros em minúsculas com hífenes.
• Escreva cada regra de estilo numa só linha.
• Não escreva à mão os prefixos dos navegadores: acrescente o comentário /*auto*/ e o Total.js prefixa as regras por si.
• Aspas simples, e CSS simples em vez de LESS ou SASS.

Plugins e componentes (jComponent)

• Nomes em minúsculas para plugins, componentes e as entradas de FUNC., MAIN. e REPO., e variáveis em minúsculas.
• Evite os sublinhados sempre que puder e mantenha o aninhamento em dois ou três níveis.
• Um plugin escreve-se com exports.; um componente usa self, config e cls.
• Desenhe para reutilizar.

Scripts SQL

• Nomes de tabelas e campos em minúsculas, tabulações para a indentação e ponto e vírgula no fim de cada instrução.
• Retire as conversões de tipo desnecessárias, formate o script e mantenha tabelas, vistas, procedimentos ou funções e índices em scripts separados.

Prefixo	Para
tbl_	tabelas, com o nome no singular
cl_	listas de códigos
view_	vistas
sp_	procedimentos armazenados
fn_	funções

Nos campos, dt inicia uma data, is inicia um booleano, as chaves seguem o padrão id ou userid e usa-se text em vez de varchar. Use id, name e dtcreated onde couberem e ordene as colunas como identificadores, campos principais, números, booleanos e datas, com as restrições de chave estrangeira no fim.

Pastas

Ponha as imagens em /img/, os scripts em /js/, os estilos em /css/, os tipos de letra em /fonts/ e os vídeos em /videos/, e nomeie os ficheiros com hífenes.

Porque ajuda

Um estilo partilhado torna um projeto fácil de passar a outros, de rever e de ampliar, e dá a um assistente de IA um padrão claro a seguir. Dê ao seu assistente esta página juntamente com as convenções do Total.js 5 para assistentes de código e o seu código ficará em linha com o resto da sua aplicação.