DEV Community

Fernanda Leite
Fernanda Leite

Posted on

Regra 3: Um bom nome é a melhor documentação

Série de artigos sobre o livro As Regras da programação de Chris Zimmerman. O livro trata de 21 regras que ajudam programadores a criarem códigos melhores. Falarei um pouco sobre cada regra do meu ponto de vista trazendo alguns exemplos e opiniões sobre o livro, com o objetivo principal de consolidar e compartilhar o conhecimento.


Esse capítulo já começa nos fazendo refletir com essa pequena citação de Shakespeare, mais especificamente da peça Romeu e Julieta:

"O que há em um nome? O que chamamos rosa
Teria o mesmo cheiro com outro nome"

Ainda existem programadores que defendem uma ideia parecida com essa, de que o nome não importa e sim o que foi nomeado. Então surgem variáveis como var n ou funções com nomes nada descritivos e sem nenhum padrão.

O nome de algo é a documentação mais importante que temos. Ele deve conter o que é importante sobre o elemento, ou seja, se for nomear uma variável o nome deve mostrar o que ela representa. Já se for nomear uma função o nome deve mostrar o que ela faz.

Abaixo temos alguns tópicos que podem ajudar nesse processo.

Não otimize usando menos pressionamento de teclas

Nosso código é lido muito mais do que é escrito. Isso quer dizer que outras pessoas que entrarem em contato com o que escrevemos não saberão o contexto no qual escrevemos uma função com o nome function sd () { ... } por exemplo. Como consequência elas gastarão muito mais tempo tentando entender o que aquele trecho faz.

Evite nomes curtos demais!

Não misture convenções

A segunda maneira de os nomes não ajudarem é devido à inconsistência. Podemos facilmente nos confundir quando não temos regras definidas para nomear elementos, como por exemplo: nomes em português ou inglês? devo usar camelCase ou snake_case? Essas são algumas das dúvidas que podem surgir tanto para quem escreve quanto para quem lê.

O mais importante é escolher as convenções que fazem sentido com seu projeto e que se integrem bem com as bibliotecas externas que você utiliza.

O livro traz outro ponto interessante "elementos semelhantes, nomes parecidos", dessa forma ao percorrer diferentes trechos do código será fácil identificar o que aquele elemento é ou faz.

Não me faça pensar

Tudo que dependa de uma tomada de decisão ou um raciocínio cuidadoso de alguém está sujeito as experiências dessa pessoa. O que quero dizer com isso é que em relação a convenções e regras não podemos deixar diferentes programadores tomarem suas próprias decisões, pois cada um vai decidir de acordo com aquilo que lhe parece melhor.

O segredo da consistência é tudo ser o mais mecânico possível. Devemos deixar nossas regras bem documentadas e utilizar ferramentas que automatizem esse processo. Com isso todos utilizam um mesmo padrão e quando trabalhamos com o código de outra pessoa parece que estamos trabalhando com nosso próprio código.


Pra finalizar o conselho do livro é _"Descubra quais das convenções de projeto você pode tornar mais mecânicas e faça isso. Você colherá os frutos durante muitos anos."
_

Image of Docusign

🛠️ Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more

Top comments (0)

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up