Padrão Geral do Código Fonte

Organização do Projeto

Essa sessão define os conceitos e organização da implementação do código, tanto da engine PlayTale, quando do primeiro jogo sendo desenvolvido para ela, o Mystery Realms.

Estrutura de Projeto

• O sistema é dividido em dois projetos Maven separados:

• PlayTale: biblioteca independente da engine, reusável em outros jogos.
• MysteryRealms: jogo que utiliza a engine PlayTale.

Base dos Pacotes

• br.eng.rodrigogml.playtale - Pacote base da Engine

• .vos - Pacote base para alocação dos VOs da Engine.

• br.eng.rodrigogml.mysteryrealms - Pacote base do jogo Mystery Realms

• .vos - Pacote base para alocação dos VOs do jogo.

Versão Java

• Java 1.8

Codificação UTF-8

• `maven-compiler-plugin` configurado com:

<encoding>UTF-8</encoding>

Estrutura Maven

• Diretórios:

• src - arquivo de diretório fonte, base do package final. Aqui devem ser inclusos arquivos que precisam estar na distribuição final, como imagens, bundles, etc..
• srcTest - arquivo de diretório com os fontes de testes do sistema, que não serão empacotados com a distribuição final.
• etc - estrutura com subdiretórios para armazenamento de arquivos relacionados ao projeto mas que não se encaixam nos antesiores, como documentos, scripts, etc.. Cada um organizado em seu próprio subdiretório.

Padrões de Código Desenvolvimento

JavaDoc

• Sempre gere javadoc em português nos atributos, classes e métodos utilizando as informações presentes na documentação wiki com explicação mais detalhada possível sobre sua finalidade, funcionamento e limitações. Pode inclusive colocar referências para as páginas wiki com mais informações.

• No javadoc a referência para os links deve ser a url completa e não o modelo de link wiki. Exemplo: no wiki a página Ficha_do_Jogador deve ser escrita com a tag <a href> com o link 'https://mysteryrealms.rodrigogml.eng.br/index.php?title=Ficha_do_Jogador', e target para abertura em nova janela.

• JavaDoc de Classe

• Nos javadoc de classe devem ser inclusas a tag '@author' com o nome Rodrigo Leitão, e a tag '@since' com a data atual no formato 'YYYY-MM-DD' (Ex: 2025-04-22)

Regras de Escrita de Código

• Sempre escrever código em inglês.
• Não gere os métodos getter e setter nos Beans/VOs.
• Utilizar sempre BigDecimal para números decimais, nunca utilizar float.
• Sempre utilizar LocalDate, LocalDateTime e LocalTime para os atributos de tempo/data.
• Atributos que tem uma quantidade limitada de valores aceitos (enumerações como tipos de armas, raridades, etc.) procure criar estrutura de 'enum' estática e pública dentro da própria classe, quando não reaproveita enum de outra classe.

Nomeação e Estrutura de Classes

• Todos objetos de dados devem usar o sufixo VO (ex: `PlayerVO`).
• VOs devem estender obrigatoriamente a classe base: RFWVO.

Exceções

• Toda exceção deve ser uma subclasse de RFWException.
• RFWException é abstrata — use subclasses específicas.
• Subclasses válidas:

• RFWCriticalException – erros críticos ou inesperados.
• RFWWarningException – falhas de ambiente, não de lógica.
• RFWSecurityException – violação de segurança ou acesso.
• RFWValidationException – validações de entrada ou estado.
• RFWValidationGroupException – múltiplas validações agrupadas.

• A única exceção fora dessa hierarquia permitida é RFWRunTimeException, para usos forçados por APIs externas (ex: interfaces que não permitem `throws`).

Construtores de Exceções

• Usar sempre que possível:

new RFWValidationException("CAMPOS_INVALIDOS", new String[]{"nome"}, originalException);

• Sempre passar o código de erro seguindo padrão: `[A-Z0-9_]+`.
• Parâmetros para i18n devem ser informados via `String[]`.
• Sempre passar a `Throwable` original quando disponível.