# Convenções de código

Onde fica cada coisa, nomes, componentes, estilo e commits.

Algumas convenções mantêm um projeto Nimbly fácil de entender, para o desenvolvedor que o escreveu, o designer que o estiliza e quem vier depois.

## Onde fica cada coisa

| O quê | Onde |
|---|---|
| Markup | Templates: `ext/tpl/` para partes reutilizáveis, `ext/uri/` para rotas |
| Lógica e preparação de dados | Bibliotecas em `ext/lib/` |
| O formato dos seus dados | Definições de recursos em `ext/data/<resource>/.meta` |
| Estilos | `ext/theme.css` e classes do Tailwind nos templates |
| Cores e temas | `ext/tailwind.theme.js` |
| Uma funcionalidade empacotada | `ext/modules/<name>/` |

Os templates continuam sem lógica e as bibliotecas não contêm HTML. Assim, um designer pode mudar qualquer parte da interface sem ler PHP, e um desenvolvedor pode mudar uma regra sem mexer no markup.

## Nomes

**Templates: primeiro o tipo, depois o assunto.** Os cartões ficam juntos, as seções também, e as páginas também:

| Tipo | Usado para | Exemplo |
|---|---|---|
| `page-` | O conteúdo de uma página | `page-about`, `page-contact` |
| `section-` | Uma seção dentro de uma página | `section-home-hero` |
| `card-` | Um item repetido | `card-project`, `card-team-member` |
| `form-` | Um formulário | `form-newsletter` |
| `icon-` | Um ícone inline | `icon-arrow-right` |
| `btn-` | Um botão ou estilo de botão | `btn-preview` |

Escreva `card-project`, não `project-card`.

**PHP: snake_case em todo lugar.** Funções, variáveis, parâmetros e nomes de arquivo: `prepare_projects_sc()`, `$project_count`, `ext/lib/prepare-projects.php`. O arquivo da biblioteca usa hífens porque também é o nome do shortcode, `[#prepare-projects#]`.

**Recursos e campos: minúsculas, plural para o recurso.** `projects`, `team-members`; campos como `title`, `title_slug`, `published`, `sort_order`.

## Componentes

Um componente é um template reutilizável com tudo de que precisa dentro da própria pasta:

```text
ext/tpl/photo-collage/index.tpl     the markup
ext/tpl/photo-collage/style.css     its own CSS, imported from ext/theme.css
```

- **Autossuficiente.** A página só chama `[#photo-collage#]`; o componente não depende da página ao redor.
- **Definido por quem chama.** O que varia a cada uso é definido antes da chamada: `[#set collage_columns=3 overwrite#]`, depois `[#photo-collage#]`.
- **Portátil.** Um bom componente funciona quando copiado para outro projeto.

A maioria das partes da interface são componentes. Transforme-o em módulo só quando ele também trouxer dados ou rotas próprios.

## Estilo

- Use as cores do tema (`primary`, `secondary` e os tokens próprios do projeto) em vez de cores fixas da paleta, para que um redesign seja uma mudança num único lugar.
- Quando uma lista longa de classes se repete em vários elementos, dê a ela um pequeno template próprio e reutilize-o. Poucas classes ficam inline.
- Coloque entre aspas as listas de classes guardadas numa variável, `[#set card-style="rounded-2xl bg-white"#]`, para que o build as encontre.

## Estilo de código

- Use sempre chaves em `if`, `else`, `for` e `while`, também em volta de uma única linha, em PHP e JavaScript.
- Corrija a causa, não o sintoma: quando falta um dado num template, corrija onde o dado é carregado; quando um layout quebra, corrija o layout em vez de esconder o overflow.
- Mantenha tudo tão pequeno quanto a necessidade atual permite. Nada de campos, configurações ou abstrações "para depois".

## Commits

Use [Conventional Commits](https://www.conventionalcommits.org/): um tipo, um escopo opcional e uma linha clara.

```text
feat(projects): filter the overview by sector
fix(header): logo and menu no longer overlap on phones
style(cards): align the card titles
```

Se mais contexto ajudar, acrescente-o depois de uma linha em branco. A primeira linha se sustenta sozinha.