Diretrizes para programação¶
<Em construção>
Este artigo lista algumas diretrizes de programação para o front-end do Portal no OpenCms. Inclui scriptlets (JSP), Javascript (JS), HTML, CSS.
Variáveis¶
Um nome de variável deve descrever a entidade que representa¶
O nome de uma variável tem que ser auto descritivo. Deve-se evitar abreviação ou letra única.
Escolha nomes descritivos e inequívocos.¶
Para isso, é possível fazer 3 perguntas no momento de escolher o nome para a variável:
- Por que existe?
- O que faz?
- Como é usada?
Os nomes de variáveis devem ser pronunciáveis.¶
Geralmente, pelos códigos, os nomes não são pronunciáveis. Quando houver necessidade de discussão presencial entre desenvolvedores e designers sobre implementação, é necessário pronunciá-la.
Os nomes devem ser pesquisáveis.¶
A partir do momento que ele é pronunciável, ele também é pesquisável, então, quando o desenvolvedor/designer precisa fazer uma busca sobre determinada variável, ao invés de ter que lembrar daquela abreviação, daquela letra única, ele sabe o nome da variável, ou, pelo menos, alguma palavra que a forma, e assim conseguir realizar uma busca por essa variável.
Use padrões consistentes em todo o projeto.¶
Essa diretriz pode ter vários sentidos, vários significados, mas a ideia-base é adotar padrões consistentes em todo projeto, no sentido daquela máxima conhecida na programação: é melhor tomar grandes decisões globais únicas que pequenas decisões locais a todo momento.
Isso pode ter alguns significados possíveis. O primeiro deles é a respeito da notação de variáveis que é usada no projeto. Existem diversas notações possíveis:
- camelCase (campos e formulários HTML, JS, JSP)
- PascalCase
- snake_case
- kebab-case (CSS)
- CONSTANT
- etc.
Regras complementares¶
Não usar sinônimos ou equivalentes para se referir às mesmas coisas.¶
Não usar a mesma palavra para diferentes conceitos nem se refira ao mesmo conceito através de diferentes palavras.¶
Usar prefixos para variáveis.¶
- form (formulário)
- event (evento)
- msg (mensagem)
Nome de variáveis¶
Para atribuir o nome para uma variável:
- O nome de uma variável pode ter um ou mais caracteres
- O primeiro caractere do nome deverá obrigatoriamente ser uma letra (HTML, CSS, JS, JSP) ou sublinhado (CSS, JS, JSP)
- Não poderão ser utilizados outros caracteres diferentes de letras, números ou sublinhado
- Não poderão ser utilizadas como nome da variável, palavras reservadas da linguagem (HTML, CSS, JS, JSP)
Referência¶