Dicas de codificação
CAUTIONUse taglibs ou HTL o máximo possível
A inclusão de scriptlets nos JSPs dificulta a depuração de problemas no código. Além disso, ao incluir scripts em JSPs, é difícil separar a lógica de negócios da camada de visualização, o que é uma violação do Princípio de responsabilidade única e do padrão de design MVC.
Gravar código legível
O código é escrito uma vez, mas é lido muitas vezes. Passar algum tempo na frente para limpar o código que escrevemos vai pagar dividendos pela estrada, já que nós e outros desenvolvedores precisamos lê-lo mais tarde.
Escolher nomes reveladores de intenção
Idealmente, outro programador não deveria ter que abrir um módulo para entender o que ele faz. Da mesma forma, eles devem ser capazes de dizer o que um método faz sem lê-lo. Quanto melhor pudermos subscrever essas ideias, mais fácil será ler nosso código e mais rápido poderemos escrever e alterar nosso código.
Na base de código AEM, as seguintes convenções são usadas:
- Uma única implementação de uma interface é chamada de
<Interface>Impl, ou sejaReaderImpl. - Várias implementações de uma interface são nomeadas
<Variant><Interface>, ou sejaJcrReadereFileSystemReader. - As classes base abstratas são nomeadas
Abstract<Interface>ouAbstract<Variant><Interface>. - Os pacotes são nomeados
com.adobe.product.module. Cada artefato Maven ou pacote OSGi deve ter seu próprio pacote. - As implementações do Java são colocadas em um pacote impl abaixo de sua API.
Observe que essas convenções não precisam necessariamente ser aplicadas às implementações do cliente, mas é importante que as convenções sejam definidas e cumpridas para que o código possa permanecer mantenível.
Idealmente, os nomes deveriam revelar a intenção. Um teste de código comum para quando os nomes não são tão claros quanto deveriam ser é a presença de comentários explicando para que é a variável ou o método:
Não se repita
DRY declara que o mesmo conjunto de códigos nunca deve ser duplicado. Isso também se aplica a coisas como literais de string. A duplicação de código abre a porta para defeitos sempre que algo tem que mudar e deve ser procurado e eliminado.
Evitar regras de CSS nu
As regras de CSS devem ser específicas ao elemento de destino no contexto do aplicativo. Por exemplo, uma regra CSS aplicada a .content .center seria muito amplo e poderia afetar muito conteúdo em todo o sistema, exigindo que outros substituíssem esse estilo no futuro. .myapp-centertext seria uma regra mais específica, pois está especificando centralizado texto no contexto do aplicativo.
Elimine o uso de APIs obsoletas
Quando uma API é obsoleta, é sempre melhor encontrar a nova abordagem recomendada em vez de depender da API obsoleta. Isso garantirá atualizações mais suaves no futuro.
Gravar código localizável
Qualquer sequência de caracteres que não esteja sendo fornecida por um autor deve ser encapsulada em uma chamada para o dicionário i18n da AEM por meio de I18n.get() em JSP/Java e CQ.I18n.get() em JavaScript. Essa implementação retornará a sequência de caracteres transmitida a ela se nenhuma implementação for encontrada, de modo que oferece a flexibilidade de implementar a localização após implementar os recursos no idioma principal.
Evitar caminhos de recursos para segurança
Embora os caminhos no JCR não devam conter espaços, a presença deles não deve fazer com que o código quebre. Jackrabbit fornece uma classe de utilitário de Texto com escape() e escapePath() métodos. Para JSPs, a interface do usuário do Granite expõe um granite:encodeURIPath() EL .
Use a API XSS e/ou o HTL para se proteger contra ataques de script entre sites
O AEM fornece uma API XSS para limpar parâmetros facilmente e garantir a segurança de ataques de script entre sites. Além disso, o HTL tem essas proteções incorporadas diretamente à linguagem de modelo. Uma planilha de API está disponível para download em Desenvolvimento - Diretrizes e práticas recomendadas.
Implementar o registro apropriado
Para código Java, o AEM oferece suporte ao slf4j como a API padrão para mensagens de registro e deve ser usado em conjunto com as configurações disponibilizadas pelo console OSGi por questões de consistência na administração. O Slf4j expõe cinco níveis diferentes de log. Recomendamos usar as seguintes diretrizes ao escolher em qual nível registrar uma mensagem:
- ERRO: Quando algo está quebrado no código, o processamento não pode continuar. Isso frequentemente ocorrerá como resultado de uma exceção inesperada. Geralmente, é útil incluir rastreamentos de pilha nesses cenários.
- AVISO: Quando algo não funcionou corretamente, mas o processamento pode continuar. Isso será frequentemente o resultado de uma exceção que esperávamos, como uma PathNotFoundException.
- INFORMAÇÕES: Informações úteis ao monitorar um sistema. Lembre-se de que esse é o padrão e que a maioria dos clientes deixará isso em vigor em seus ambientes. Portanto, não o use excessivamente.
- DEPURAR: Informações de nível inferior sobre processamento. Útil ao depurar um problema com suporte.
- TRACE: As informações de nível mais baixo, como métodos de entrada/saída. Geralmente, isso só será usado por desenvolvedores.
No caso de JavaScript, console.log só deve ser usada durante o desenvolvimento e todas as declarações de log devem ser removidas antes do lançamento.
Evitar a programação do culto de carga
Evite copiar o código sem entender o que ele faz. Na dúvida, é sempre melhor perguntar a alguém que tem mais experiência com o módulo ou a API que você não está claro.
