1. Escolher o âmbito
Decidir se a versão 1 do software é apenas de leitura ou de leitura e escrita. Decidir também se suporta apenas `ENTRY` ou `ENTRY` e `LIB`.
Avançar rápido sem perder o essencial
Esta página funciona como uma rampa de lançamento prática. Resume o que uma equipa deve estabilizar nos primeiros dias: âmbito, modelo interno, leitura, escrita e testes. Não substitui as especificações, mas ajuda a não dispersar o esforço demasiado cedo.
O que fixar desde o início
Antes de programar refinamentos, a equipa deve alinhar terminologia, formatos suportados e comportamento do writer.
2. Fixar o núcleo de leitura
Tudo deve convergir para um único parser de texto, mesmo quando a entrada chega em `.eevz` ou num `.eevcz` já emitido que só precisa de ser lido. A compressão é transporte, não uma segunda linguagem.
3. Desenhar um modelo limpo
Criar estruturas claras para a biblioteca, as entradas, os blocos globais, as matrizes, os modos e os `peak_tracks`. Evitar guardar linhas brutas durante o maior tempo possível.
MVP razoável
- leitura de `.eev` e `.eevz`
- suportar primeiro `ENTRY`, depois `LIB` se necessário
- validação com erros bloqueantes e avisos legacy
- usar o writer canónico apenas para os campos que o software realmente compreende
- testes de round-trip com exemplos reais
Versão 2 útil
- suporte completo de `LIB`
- suporte de leitura para `.eevc` e `.eevcz`
- preservação mais fina das secções opcionais
- ferramentas de diff e diagnóstico
- compatibilidade legacy mais rica
Primeiro sprint recomendado
O objetivo do primeiro sprint não é cobrir toda a especificação. É produzir uma cadeia fiável, explicável e testável.
Fazer parsing de um `ENTRY` textual
Começar pelo caso mais simples. Ler o cabeçalho, abrir `@entry`, reconhecer os blocos principais, produzir um modelo em memória e devolver diagnósticos legíveis.
Reemitir em ordem canónica
A partir do modelo interno, produzir texto estável e determinístico. O objetivo é que duas exportações idênticas gerem a mesma saída.
Adicionar o transporte comprimido
Quando o texto funcionar, adicionar a camada `.eevz`. Descomprimir antes de ler, comprimir depois de escrever. Manter o mesmo núcleo funcional.
Testar em casos reais
Misturar exemplos limpos, casos legacy, campos em falta e captações reais. Um parser que só vê exemplos perfeitos continua frágil.
Armadilhas frequentes
- confundir nível de qualidade com estatuto documental
- deixar que o cabeçalho da biblioteca descreva uma única entrada
- reemitir automaticamente tudo o que foi tolerado na leitura
- tratar o hash como uma questão do contentor comprimido
Reflexo saudável
Quando surgir uma dúvida, voltar a três perguntas: isto pertence ao contrato público, à estratégia de implementação ou à qualidade da captação? Essa separação evita muita confusão no código e nas discussões de produto.
Entrega credível de primeira versão
Uma primeira versão credível sabe ler corretamente um subconjunto claro do formato, produzir diagnósticos honestos, reemitir texto determinístico e documentar explicitamente aquilo que ainda não suporta. Isso não é uma fraqueza: é uma base saudável.