Começando a praticar Código Limpo

Você já deve ter ouvido falar que “um bom código dispensa comentários” ou ter achado que praticar código limpo é muito difícil, certo?

Nesse artigo vou te contar toda a verdade sobre a parte prática do código limpo!

Se você caiu aqui de paraquedas, seja muito bem-vindo!

Antes, dá uma olhada no que a gente já conversou sobre Código Limpo.

Começando a praticar Código Limpo

E aí no meio disso tudo alguém deve ter te falado que se você nomear bem as coisas, seja uma variável, uma função ou uma classe, por exemplo, não vai precisar escrever comentários sobre aquilo.

Por fim, talvez você tenha impetuosamente tentado absorver toda essa história de Código Limpo para si.

E claro, cometido o mesmo erro que eu quando ouvi falar do assunto pela primeira vez:

Achar que Código Limpo é dar um nome enorme e descritivo para as coisas no seu código sem medo de ser feliz.

Sinto lhe informar, mas nem é.

Nomes são importantes

Para começar eu quero deixar bem claro que sim, nomes são importantes!

Eu tive um professor que me ensinou bem o quanto os nomes podem ser importantes com duas atitudes bem interessantes:

• Ele nunca aceitava quando um estudante se apresentava somente pelo primeiro nome. Era sempre exigido nome e sobrenome;

• Certa vez um estudante argumentou que uma certa configuração era “só um nome” e ouviu tanto o professor discursar sobre como ele não iria querer ser chamado de outra coisa além do seu nome que, com certeza, nunca mais se esqueceu disso.

Pois é, eu estava lá, eu era o estudante. xD

O problema com nomes é que nós nunca aprendemos nenhuma técnica de nomeação.

Normalmente é bem subjetivo e, apesar disso, nós humanos somos muito bons nisso.

A gente vive nomeando as coisas. Só que nem sempre um nome vai conseguir carregar toda a informação que você queria passar sobre algo.

Se eu nomeio meu cachorro de Monstro, eu posso te confundir se estou fazendo uma referência a Harry Potter ou ao Kleber Bambam.

Só que na verdade eu só dei esse nome a ele porque o mesmo apareceu na minha casa a noite enquanto eu dormia me dando um baita susto.

E vamos combinar: seja qual for o motivo, este é um bom nome.

Então como já conversamos no artigo anterior, sempre que nos deparamos com uma subjetividade necessária para praticar código limpo e no nosso trabalho, procuramos criar padrões.

Padrões

Já que não podemos carregar tanta informação em nomes, vamos padronizar o que minimamente esperamos de um nome.

É preciso ter boas práticas em programação, seja em PHP, Java, JavaScript mas como ter boas práticas ao escrever um código?

Neste artigo vamos nos concentrar em boas práticas bases para nomeação principalmente de variáveis e funções de apoio, ou seja, funções que não são métodos.

E quem sabe a gente não fale especificamente de cada uma delas em postagens futuras incluindo também classes, interfaces, métodos e tudo mais!

Nomes têm significado

Primeira dica infalível: nunca, jamais, em hipótese alguma reaproveite exatamente o mesmo nome em outro contexto.

Na dúvida se ainda está no mesmo contexto para reutilizar uma variável, só não reutilize.

Vai por mim, você não vai querer ter dois cachorros chamados Monstro, aliás eu já tô começando a questionar se esse nome é legal mesmo.

Dar o mesmo nome para duas coisas diferentes requer certa maestria e cuidado, ainda mais quando se trata em praticar código limpo.

Obviamente você pode chamar seus dois cachorros de… bem… “Cachorro”.

Mas usar esse nome para se referenciar especificamente a um deles faz com que você perca a clareza na sua fala.

Porém um bom exemplo onde algo similar a isso funciona é no filme Bird Box onde a Sandra Bullock chama as crianças que a acompanham de boy e girl.

Nesse caso o contexto inserido pelo filme deixa claro a quem ela está se referenciando, o significado de menino e menina fica claro.

O significado na hora de praticar Código Limpo

Segundo o dicionário do Google um “significado” é uma relação de reconhecimento.

Algo com significado é reconhecível. Então um nome deve dar significado ao que nomeia.

No livro Clean Code. A Handbook of Agile Software Craftsmanship existe um capítulo inteiro falando sobre a importância, boas práticas e cuidados com os nomes que damos às coisas em nosso código.

Como sempre, tudo é bem subjetivo e o Robert tenta oferecer bastante exemplos de como você pode alcançar essa qualidade de software.

Eu vou falar sobre as dicas dele com uma pitadinha de outras dicas de minha autoria agora.

Classes gramaticais

Achou que bastava saber matemática para programar bem? Achou errado!

O próprio tio Robert define que variáveis devem ser substantivos e funções verbos.

Pois é, isso são classes gramaticais e para dar bons nomes vamos precisar ter uma noção não só delas como das outras 8 que existem.

Para te ajudar a lembrar desse conteúdo, eu separei um artigo da Daniela Diana sobre classe de palavras que é muito bom e sucinto.

Boas práticas

Então temos as seguintes boas práticas:

Nunca utilize pronomes, artigos (alô WordPress) e interjeições.

Ex.: $theUser; setAPost($aPost); $myArticle; $yay;

Evite ao máximo utilizar numerais, preposições e conjunções

Essas classes só têm sentido em frases maiores o que vai te obrigar a dar um nome bem grande para que tenham significado.

Além disso, normalmente isso vai depender tanto do contexto que está inserida que talvez elas não sejam necessárias, pois sua própria localização já dirá o que você quis dizer com o nome.

Observe o exemplo:

$userWhoWroteThisPost;
getTwoUsers($condition);
$allArticlesExceptWithMoreThanThreeYears;

Utilize substantivos e adjetivos para as suas variáveis como:

$user;
$adminUsers;
$favoritePosts;

Utilize verbos e advérbios para funções como:

getMostRecentArticle();
findUserById($id);
bind($eventTrigger);

Siglas

A gente de computação adora falar orientado a siglas, né?

É SaaS, IaaS, DRY, MVC, DDD, JSON, CSS, JS, BI, IOT, POC, TDD, CMS, DBMS, SOLID, OOP, CRM, DNS, ERP, FTP e ainda tem mais…

HTTP, SSL, TCP/IP, SSH, DB, LAN, WAN, HTML, XML, SQL, GNU, PHP, UI, UX, URL, VPN, VM, ASCII, BIOS, DDoS, SSD, ETL, MAC, etc.

Ufa!

Inclusive, crítica forte a nós mesmos:

Essas siglas muitas das vezes vêm para complicar e rebuscar uma fala, quando na verdade significam coisas extremamente simples.

Eu acho muito legal e democrático evitar usar siglas a todo o momento que falamos de tecnologia principalmente sem introduzi-las anteriormente a todos.

Inclusive, estamos tão acostumados a isso que fazemos no momento de darmos nomes a coisas nos nossos códigos.

Isso é uma prática antiga.

Da época em que ao se escrever um algoritmo era necessário ficar atento ao tamanho final do arquivo a fim de que o mesmo coubesse dentro de armazenamento móvel como os disquetes (!!) e cartões perfurados (!!!).

Hoje em dia essa é a menor das nossas preocupações, então não use siglas e abreviações na hora de praticar código limpo!

Evite nomes muito parecidos

Pense em distinções claras!

Tente preencher uma chave para cara item do array no código abaixo:

$response = [
  getMostRecentPostComments(),
  getMostRecentCommentedPosts(),
  getMostRecentPostComment(),
  getMostRecentCommentedPost(),
  getMostRecentPostsComments()
];

O nome de cada função isoladamente não está ruim.

Mas veja como fica difícil de identificar e é bem fácil de confundir em que posição estão qual(is) postagem(ns) e qual(is) comentário(s).

E isso é bem comum nos códigos do dia a dia de trabalho, principalmente quando não há uma estratégia de revisão de código antes da entrega.

A fim de evitar esse mesmo problema é bom desistirmos de usar prefixos e sufixos nos nossos nomes.

Se você precisa classificar algo através disso, talvez seja o caso de usar uma outra estrutura por fora que dê algum sentido a eles.

Seja coerente

Existem múltiplas palavras chave para um mesmo sentido.

As palavras search e find podem ser usadas dando o mesmo sentido de busca, por exemplo.

Nestes casos é bom que o código mantenha a coerência.

Em produção textual, a coerência é o que faz o seu texto não perder o sentido da mensagem.

Então os termos já introduzidos como referência são reutilizados com mais significado durante o texto conforme vão sendo apresentados novamente.

Em programação nós devemos fazer o mesmo.

Por isso devemos optar por uma estratégia de padronização:

Se decidirmos que funções find são utilizadas para buscar um registro no banco de dados, não vamos criar uma função searchById com o mesmo intuito.

Essa parte é interessante!

No livro Clean Code, o Robert não deixa de mencionar que podemos sim ter funções com nomes find e search, desde que elas ofereçam significados (ou seja, funcionalidades) diferentes.

Então podemos dizer que a funções com find no nome significam implicitamente uma busca no banco de dados.

Enquanto as com search buscam numa estrutura de dados específica da nossa aplicação.

Olha a importância da padronização entre a equipe aí de novo na hora de você praticar código limpo.

Idioma e Case Types na hora de praticar código limpo

Isso é meio clichê, mas realmente é necessário: programem em inglês.

Se você não tem o domínio desse idioma, aproveite a oportunidade e pratique.

Esse é o ambiente perfeito para você errar sem vergonha alguma, pois até quem é fluente no idioma vai escrever nomes ruins.

O pior dos casos é ficar com códigos em “portunglês”.

É extremamente difícil escrever tudo em português visto que uma hora ou outra você vai precisar usar coisas nativas da própria linguagem de programação em que estiver e que fatalmente estarão em inglês.

Apesar disso percebam como ter conhecimentos em línguas foi importante neste artigo mesmo pelas regras para o português mesmo.

Por fim, gostaria de atentar aos Case Types. Não consegui dar traduções a eles, então os termos terão que ficar em inglês mesmo:

• Camel Case: comum para nomear funções. Gosto de usar este case também para variáveis que armazenam objetos. Formato: camelCase. Ex: getUserById(); $newUser = new User(); $newUser->encryptPassword();
• Pascal Case: é assim que nomeamos classes, não é legal utilizar este case em nenhum outro caso. Formato: PascalCase. Ex: class DocumentModel { // ... }
• Snake Case: comum para nomes em geral e vem em dois sabores:
  
  • Upper Snake Case: comumente utilizada para nome de constantes. Formato: UPPER_SNAKE_CASE. Ex.: const BASE_URL = 'blog.geekhunter.com.br/';
  • Lower Snake Case: utilizada nas mais diversas coisas. Eu gosto de usar em nomes de arquivos, variáveis com valores simples (não objetos) e ids em tags HTML.
    No PHP as funções nativas estão quase todas neste case type. Formato: lower_snake_case.
    Ex.: $pdf_content = file_get_contents('holy_bible.pdf'); $html = '<div id="game_canvas"></div>';
• Kebab Case: muito utilizado para definir slugs de URIs e para nomes de classes em CSS. Formato: kebab-case. Ex: $slug = 'codigo-limpo'; $html = '<div class="container-fluid"></div>‘;

Espero que tenham gostado! Até a próxima!