# 06 — Boas Práticas de Programação (G-ART)

> **Propósito:** registrar as melhores práticas de programação a serem aplicadas
> **sempre** que qualquer alteração ou correção for feita neste programa.
> Servem de checklist obrigatório antes de concluir qualquer mudança.

**Regra:** antes de considerar uma alteração concluída, confira os itens abaixo.
Eles são o mesmo espírito do fluxo de validação pós-correção
(`Engine/run_after_fix.sh`), mas cobrem também **qualidade de código** e
**convenções do projeto**.

---

## 1. Correções de código

1. **Sempre valide após corrigir** — rode `./Engine/run_after_fix.sh` (lint +
   testes). Nunca declare uma correção pronta sem que lint e a suíte passem.
2. **Toda correção já corrigida vira registro** — registre o problema em
   `Engine/docs/05_EXPERIENCIAS.md` para que não se repita.
3. **Mude o mínimo necessário** — altere apenas o que resolve o problema; evite
   refatorar código não relacionado na mesma mudança.

## 2. Tempo e FCPXML

4. **Nunca use `float` para tempo** — toda duração/offset é `TimeValue`
   (fração racional `"600/2400s"`). Float introduz erro de arredondamento.
5. **`offset` é a posição na timeline; `start` é o in-point na origem** — não
   confundir nas edições de clip.
6. **Markers são filhos dos clips, não irmãos** — e `<spine>` é a storyline
   primária; connected clips penduram-se com atributo `lane`.
7. **Preserve sidecars em bundles `.fcpxmld`** — ao gravar um bundle, copie os
   arquivos de dados; caso contrário destrói object-tracking/Cinematic.

## 3. Estrutura e arquitetura

8. **Mantenha o núcleo desacoplado** — `fcpxml/` não conhece o protocolo MCP;
   `server.py` é a camada de transporte. Não vazem lógica MCP para o núcleo.
9. **Use o padrão de dispatch** — sem cadeias gigantes de `if/elif`; use
   `TOOL_HANDLERS` (dicionário nome → handler assíncrono).
10. **Reaproveite os helpers centrais** — `_parse_project()`, `_resolve_io_paths()`,
    `_setup_modifier()`, etc. Não duplique parse/validação de caminho.
11. **Nunca sobrescreva o original** — use `generate_output_path()` e crie
    `_modified`, `_chapters`, etc.
12. **Mantenha o `MarkerType` como single source of truth** — a serialização
    (parse/escrita) vive no enum, não espalhada por handlers.

## 4. Segurança

13. **Sempre use `safe_xml.py` (defusedxml)** — todos os entry points de parse;
    jamais `xml.etree` cru com input não confiável.
14. **Valide caminhos com `_validate_filepath` / `_validate_output_path`** — o
    sandbox de I/O existe para impedir escrita fora do permitido.
15. **Rejeite payloads excessivamente aninhados** — `_check_json_depth` protege
    contra payloads além de 50 níveis.
16. **Nunca registre/commite segredos ou chaves** — nem em logs, nem em código.

## 5. Qualidade e clareza

17. **Sem comentários desnecessários** — código deve ser autoexplicativo;
    comente o *porquê*, não o *o quê*.
18. **Mimice as convenções do projeto** — mesma estrutura de imports, nomes,
    padrões e bibliotecas já usadas nas vizinhas.
19. **Lazy import de dependências opcionais** — `media_intel` (librosa) e
    `transcribe` (Whisper) importam sob demanda e degradam com graça (`None`).
20. **Convenções de teste** — use `examples/sample.fcpxml` + fixtures XML inline;
    `sample.fcpxml` NÃO é DTD-conformante, não o use como fixture de validade DTD.

## 6. Checklist final antes de concluir uma alteração

- [ ] `./Engine/run_after_fix.sh` passou (lint zero erros + todos os testes).
- [ ] Problema registrado em `Engine/docs/05_EXPERIENCIAS.md` (se aplicável).
- [ ] Nenhum `float` usado em matemática de tempo.
- [ ] Nenhum caminho original sobrescrito.
- [ ] `safe_xml.py` usado em todo parse de input não confiável.
- [ ] Nenhum segredo registrado ou commitado.
- [ ] Mudança mínima, sem refatoração não relacionada.
- [ ] Boa prática nova aprendida adicionada a esta lista.