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

> As convenções da comunidade Total.js para JavaScript, nomes, esquemas, require(), CSS, plugins e componentes do jComponent, scripts SQL e pastas, para que todos os projetos se leiam da mesma forma e uma equipa ou um assistente de IA os possa continuar.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: pt
Content-SHA256: 4a6e6439af8352bad49174e8f413c23da1685b79010e9e330012d4991dc8d489
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

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](https://github.com/totaljs-es/guidelines) (a revisão consultada está registada em [ai-sources.json](/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](/en/docs/totaljs-agent-conventions/).

## 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](/en/docs/totaljs-agent-conventions/) e o seu código ficará em linha com o resto da sua aplicação.