Dicas de codificação coding-tips

Use taglibs ou HTL o máximo possível use-taglibs-or-htl-as-much-as-possible

A inclusão de scriptlets em JSPs dificulta a depuração de problemas no código. Além disso, ao incluir scriptlets em JSPs, é difícil separar a lógica de negócios da camada de exibição, o que é uma violação do Princípio de Responsabilidade Única e do padrão de design do MVC.

Gravar código legível write-readable-code

O código é gravado uma vez, mas lido várias vezes. Gastar algum tempo antes para limpar o código escrito paga dividendos adiante à medida que você e outros desenvolvedores o leem mais tarde.

Escolher nomes reveladores de intenção choose-intention-revealing-names

Idealmente, outro programador não deve 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 você se inscrever nessas ideias, mais fácil será ler o código e mais rápido poderá escrever e alterar o código.

Na base de código AEM, as seguintes convenções são usadas:

  • Uma única implementação de uma interface é chamada <Interface>Impl, ou seja, ReaderImpl.
  • Várias implementações de uma interface são nomeadas como <Variant><Interface>, ou seja, JcrReader e FileSystemReader.
  • As classes base abstratas são nomeadas como Abstract<Interface> ou Abstract<Variant><Interface>.
  • Os pacotes são nomeados como 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 da API.

Essas convenções não se aplicam necessariamente às implementações do cliente, mas é importante que elas sejam definidas e seguidas para que o código possa ser mantido.

Idealmente, os nomes devem revelar sua 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 serve a variável ou o método:

Não claro
Limpar
int d; //tempo decorrido em dias
int elapsedTimeInDays;
//obter imagens com marcas de formatação
getItems() de Lista pública {}
lista pública getTaggedImages() {}

Não se repita don-t-repeat-yourself

DRY indica 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 precisa mudar e deve ser buscado e eliminado.

Evitar regras CSS nuas avoid-naked-css-rules

As regras CSS devem ser específicas para o elemento de destino no contexto do aplicativo. Por exemplo, uma regra CSS aplicada a .content .center seria muito ampla e poderia afetar muitos conteúdos no sistema, exigindo que outros substituíssem esse estilo no futuro. Ao passo que .myapp-centertext seria uma regra mais específica, pois está especificando o texto centralizado no contexto do seu aplicativo.

Eliminar o uso de APIs obsoletas eliminate-usage-of-deprecated-apis

Quando uma API é descontinuada, é sempre melhor encontrar a nova abordagem recomendada em vez de depender da API descontinuada. Isso garantirá atualizações mais tranquilas no futuro.

Gravar código localizável write-localizable-code

Qualquer cadeia de caracteres que não esteja sendo fornecida por um autor deve ser encapsulada em uma chamada para o dicionário i18n do AEM por meio de I18n.get() em JSP/Java e CQ.I18n.get() no JavaScript. Essa implementação retornará a string passada para ela se nenhuma implementação for encontrada, portanto, oferece a flexibilidade de implementar a localização após implementar os recursos no idioma principal.

Evitar caminhos de recursos para segurança escape-resource-paths-for-safety

Embora os caminhos no JCR não devam conter espaços, a presença deles não deve causar a quebra do código. O Jackrabbit fornece uma classe de utilitário de texto com os métodos escape() e escapePath(). Para JSPs, a interface do usuário do Granite expõe uma função EL ** granite:encodeURIPath().

Usar a API XSS e/ou o HTL para proteger contra ataques de script entre sites use-the-xss-api-and-or-htl-to-protect-against-cross-site-scripting-attacks

O AEM fornece uma API XSS para limpar facilmente os parâmetros e garantir a segurança contra ataques de script entre sites. Além disso, o HTL tem essas proteções incorporadas diretamente na linguagem de modelo. Uma folha de características da API está disponível para download em Desenvolvimento - Diretrizes e práticas recomendadas.

Implementar o registro apropriado implement-appropriate-logging

Para o código Java™, o AEM é compatível com o slf4j como a API padrão para mensagens de registro e deve ser usado com as configurações disponibilizadas pelo console OSGi para fins de consistência na administração. O Slf4j expõe cinco níveis de log diferentes. O Adobe recomenda usar as seguintes diretrizes ao escolher em qual nível registrar uma mensagem:

  • ERRO: quando algo está com defeito no código, o processamento não pode continuar. Isso frequentemente ocorrerá como resultado de uma exceção inesperada. É útil incluir rastreamentos de pilha nesses cenários.
  • AVISO: quando algo não funcionou corretamente, mas o processamento pode continuar. Isso geralmente será o resultado de uma exceção esperada, como PathNotFoundException.
  • INFO: informações que seriam ú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.
  • DEBUG: 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. Normalmente, isso só será usado por desenvolvedores.

Se houver JavaScript, o console.log deverá ser usado somente durante o desenvolvimento e todas as instruções de log deverão ser removidas antes do lançamento.

Evite programação cult de carga avoid-cargo-cult-programming

Evite copiar o código sem entender seu funcionamento. Em caso de dúvida, é sempre melhor perguntar a alguém que tem mais experiência com o módulo ou a API que você não sabe ao certo.

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2