Clean Code: Funções

Esse artigo é um de uma série que fala sobre vários tópicos relacionados a Código limpo, seguem os tópicos relacionados abaixo:

• Código Limpo: 1. Introdução

• Código Limpo: 2. Funções [Você está aqui!]

• Código Limpo: 3. Exceptions e Tratamento de Erros

Vamos falar um pouco como podemos melhorar a compreensão de nosso código no contexto de funções.

IMPORTANTE: Todas as sugestões e práticas aqui descritas se aplicam a funções, métodos e/ou variações, independente do paradigma escolhido ou da linguagem que está sendo utilizada e aplicando os conceitos, então quando me refiro somente por função ou método, estou falando da conceitos em ambos.

Bom, acho que antes de falarmos de como construir um código limpo e boas práticas, vamos falar do que precisamos evitar fazer.

Como NÃO ter um código limpo com funções/métodos

Código NÃO limpo nós normalmente identificamos logo na primeira leitura de um trecho de código e sentimos que não estamos entendendo o que está fazendo, o que está acontecendo. Ter certa complexidade no código e/ou os nomes não dizem muito sobre o que está acontecendo no código.
Seguem abaixo alguns aspectos que podemos considerar quando estamos construindo ou refatorando um código existente:

1.Evite nomes parecidos, podem confundir quando colocar a chamada em outro lugar:

func upTime() {
    // current UpTime
}

func updTime() {
    // Update time
}

Já teria gerado um bug com certeza, porque ÓBVIO que eu chamaria a função incorreta.

2.Evite acrônimos que confundam, podem ser mal interpretados e confundir a pessoa desenvolvedora:

func genymdhms() {
    // Generation Timestamp (Y-m-d h:m:s)
}
func modymdhms() {
    // Modification Timestamp (Y-m-d h:m:s)
}

Não iria deduzir nunca o que essas funções fazem, sofrido ("Crying in Spanish").

3.Evite as letras "L" e "Ó" minúsculas que podem parecer "1" e "0"(zero) respectivamente, podem deixar o código confuso, como o exemplo abaixo que já enche os nossos olhos de lágrimas de sofrimento:

    int a = 1
    if (O == 1)
        a = O1
    else
        l = 01

4.Evite nomes que tenham no nome apenas uma letra, lendo e interpretando o código abaixo na base do ódio:

    x = 1
    a = x + 2

5.Evite usar números sequenciais em nomes ( a1, a2, ..., aN ), não expressa nenhuma informação que ajude a compreender o contexto do código.

6.Evite palavras distintas que podem expressar informações do mesmo contexto ou não. Leio o código abaixo e me sinto como o confuso John Travolta em Pulp Fiction:

func getProductData() {
    // Gets product id, name and description
}
func getProductInfo() {
    // Gets product specification
}

7.Evite adicionar contextos desnecessários como o nome ou as siglas da empresa em todas as classes, métodos e funções, prejudicando a pesquisa:

func myCompanyNameGenTimestamp() {
    ...
}

func myCompanyNameUpdTimestamp() {
    ...
}

8.Evite linguagem informal e/ou gírias. Exemplos: whack(), eatMyShorts(), abort().

9.Quanto mais longo é um programa, mais tempo e difícil para entender o que ele faz.

Como construir um código limpo com funções/métodos

1.Crie nomes significativos 1: Acho que todo mundo se depara não com o desafio de criar uma função método com um cálculo matemático, mas sim, como nomear essa função que executa este cálculo matemático complexo.

"Escolher bons nomes leva tempo, mas economiza mais." - Robert C. Martin

Funções/Métodos devem fazer apenas uma coisa, devem fazê-la muito bem e apenas ela, devem comunicar o que fazem e como usa de forma compreensível 2 e que revelem seu propósito. Cuide de seus nomes e troque quando encontrar melhores. Exemplo de função com nomes bem definidos: Números ímpares num função:

func oddNumber(number: int) bool {
    if(number / 2 % 0) {
        return true
    }
}

2.Use nomes a partir do domínio(projeto, negócio, objetivo) da solução ou do problema da aplicação

3.Nomes curtos geralmente são melhores contanto que sejam objetivos e compreensíveis.

4.Crie nomes que sejam pronunciáveis e pesquisáveis e de fácil escuta:

func generationTimestamp() {
    // Generation Timestamp (Y-m-d h:m:s)
}

func modificationTimestamp() {
    // Modification Timestamp (Y-m-d h:m:s)
}

Refatorei o código das funções com acrônimos e já vejo uma luz no fim do túnel de que posso melhorar, como a vida é bela!

5.Blocos dentro de instruções if/else, while devem ter uma linha, porque a chamada dentro do bloco pode receber um nome mais descritivo.

Existe o receio de renomear as coisas por outras pessoas do time serem contra, todos devem na verdade agradecer que os nomes mudaram para melhor.

Perguntas boas para se fazer durante o processo:

1. Como fazer uma função/métodos transmitir seu propósito?
2. Quais atributos das nossas funções/métodos que permitirão um leitor comum deduzir o tipo de programa ali contido?
3. Funções devem ser pequenas: Qual o tamanho ideal? 3, 4 linhas?

Faltou alguma coisa?

Se tu acha algo no artigo ficou confuso, coloca nos comentários ou me manda uma mensagem. Se conhecer mais dicas e práticas, coloca nos comentários para a galera já ler na sequência, vamos enriquecer nossa discussão sobre o assunto. =]

Referências usadas no artigo:

[1] Martin, Robert, Código Limpo: Habilidades práticas do Agile Software, 2011, Alta Books, Rio de Janeiro.

[2] Fowler, Martin, Refactoring: Improving the Design of Existing Code, 2019, Pearson, EUA.