78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
# 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.
|