{"id":725,"date":"2024-07-01T10:25:21","date_gmt":"2024-07-01T13:25:21","guid":{"rendered":"https:\/\/adrianosantostreina.com.br\/blog\/?p=725"},"modified":"2024-07-08T21:28:30","modified_gmt":"2024-07-09T00:28:30","slug":"codigo-limpo-parte-3-comentarios-eficientes-o-terceiro-pilar-do-codigo-limpo","status":"publish","type":"post","link":"https:\/\/adrianosantostreina.com.br\/blog\/codigo-limpo-parte-3-comentarios-eficientes-o-terceiro-pilar-do-codigo-limpo\/","title":{"rendered":"C\u00f3digo-Limpo Parte 3: Coment\u00e1rios Eficientes – O Terceiro Pilar do C\u00f3digo-Limpo"},"content":{"rendered":"\n

Coment\u00e1rios no c\u00f3digo s\u00e3o ferramentas poderosas para desenvolvedores. Eles ajudam a esclarecer a l\u00f3gica, documentar decis\u00f5es e fornecer contexto adicional que n\u00e3o \u00e9 imediatamente evidente apenas pela leitura do c\u00f3digo. No entanto, a utiliza\u00e7\u00e3o de coment\u00e1rios deve ser feita com cautela e de forma estrat\u00e9gica para evitar problemas como a duplica\u00e7\u00e3o de informa\u00e7\u00e3o ou desatualiza\u00e7\u00e3o. Robert C. Martin, em “C\u00f3digo-Limpo”, enfatiza a import\u00e2ncia de escrever coment\u00e1rios eficientes e \u00fateis. Este artigo explora como fazer isso, destacando a import\u00e2ncia de bons coment\u00e1rios, suas vantagens e como implement\u00e1-los de forma eficaz.<\/p>\n\n\n\n\n\n\n\n

Por que \u00e9 importante um c\u00f3digo-limpo?<\/h4>\n\n\n\n

C\u00f3digo-limpo \u00e9 aquele que \u00e9 f\u00e1cil de ler, entender e modificar. Manter um c\u00f3digo-limpo traz v\u00e1rias vantagens, incluindo:<\/p>\n\n\n\n

    \n
  1. Legibilidade<\/strong>: Um c\u00f3digo f\u00e1cil de ler \u00e9 mais f\u00e1cil de entender, o que \u00e9 crucial para a colabora\u00e7\u00e3o entre desenvolvedores.<\/li>\n\n\n\n
  2. Manuten\u00e7\u00e3o<\/strong>: C\u00f3digo claro e bem-estruturado facilita a manuten\u00e7\u00e3o e a refatora\u00e7\u00e3o, reduzindo o tempo e esfor\u00e7o necess\u00e1rios para essas tarefas.<\/li>\n\n\n\n
  3. Colabora\u00e7\u00e3o<\/strong>: Facilita a colabora\u00e7\u00e3o entre desenvolvedores, permitindo que todos possam rapidamente entender a l\u00f3gica e o fluxo do c\u00f3digo.<\/li>\n\n\n\n
  4. Redu\u00e7\u00e3o de Erros<\/strong>: C\u00f3digo bem-organizado e leg\u00edvel \u00e9 menos propenso a erros, pois \u00e9 mais f\u00e1cil identificar e corrigir problemas.<\/li>\n<\/ol>\n\n\n\n

    Os principais pilares<\/h4>\n\n\n\n

    Os principais pilares do c\u00f3digo-limpo s\u00e3o pr\u00e1ticas e princ\u00edpios que guiam os desenvolvedores na cria\u00e7\u00e3o de c\u00f3digo de alta qualidade. Cada pilar aborda um aspecto espec\u00edfico do desenvolvimento de software, contribuindo para a cria\u00e7\u00e3o de um sistema que \u00e9 f\u00e1cil de entender, manter e evoluir. Aqui est\u00e3o os principais pilares do c\u00f3digo-limpo:<\/p>\n\n\n\n

      \n
    1. Nomes significativos<\/li>\n\n\n\n
    2. Fun\u00e7\u00f5es pequenas e focadas<\/li>\n\n\n\n
    3. Coment\u00e1rios eficientes<\/li>\n\n\n\n
    4. Formata\u00e7\u00e3o consistente<\/li>\n\n\n\n
    5. Tratamento adequado de erros<\/li>\n\n\n\n
    6. Estrutura coesa e baixo acoplamento<\/li>\n\n\n\n
    7. Testes automatizados<\/li>\n\n\n\n
    8. Refatora\u00e7\u00e3o cont\u00ednua<\/li>\n\n\n\n
    9. C\u00f3digo simples e direto<\/li>\n\n\n\n
    10. Princ\u00edpios SOLID<\/li>\n<\/ol>\n\n\n\n

      Neste artigo, focaremos no terceiro pilar: Coment\u00e1rios Eficientes.<\/p>\n\n\n\n

      Terceiro Pilar: Coment\u00e1rios Eficientes<\/h4>\n\n\n\n

      Coment\u00e1rios eficientes s\u00e3o aqueles que realmente agregam valor ao c\u00f3digo, explicando o “porqu\u00ea” por tr\u00e1s das decis\u00f5es de design e fornecendo contexto adicional. Eles n\u00e3o devem repetir o que o c\u00f3digo j\u00e1 diz claramente, mas sim complementar a compreens\u00e3o do desenvolvedor. Coment\u00e1rios bem escritos ajudam a documentar inten\u00e7\u00f5es, explicam racioc\u00ednios complexos e facilitam a colabora\u00e7\u00e3o.<\/p>\n\n\n\n

      A Import\u00e2ncia de Coment\u00e1rios Eficientes<\/h5>\n\n\n\n

      Robert C. Martin, em seu livro “C\u00f3digo-Limpo”, destaca que coment\u00e1rios s\u00e3o frequentemente usados como um “rem\u00e9dio” para c\u00f3digo mal escrito. Ele argumenta que, em vez de usar coment\u00e1rios para explicar o c\u00f3digo, os desenvolvedores devem se esfor\u00e7ar para escrever um c\u00f3digo que n\u00e3o precise de explica\u00e7\u00f5es. No entanto, ele reconhece que h\u00e1 momentos em que coment\u00e1rios s\u00e3o necess\u00e1rios e \u00fateis. Aqui est\u00e3o algumas situa\u00e7\u00f5es onde coment\u00e1rios eficientes s\u00e3o cruciais:<\/p>\n\n\n\n

        \n
      1. Decis\u00f5es de Design Complexas<\/strong>: Quando uma decis\u00e3o de design \u00e9 tomada para resolver um problema espec\u00edfico ou para contornar uma limita\u00e7\u00e3o, \u00e9 \u00fatil documentar essa decis\u00e3o com um coment\u00e1rio. Isso ajuda futuros desenvolvedores a entender o contexto e a raz\u00e3o por tr\u00e1s da implementa\u00e7\u00e3o.<\/li>\n\n\n\n
      2. Regras de Neg\u00f3cio Espec\u00edficas<\/strong>: Documentar regras de neg\u00f3cio diretamente no c\u00f3digo ajuda a manter o entendimento do dom\u00ednio dentro do pr\u00f3prio c\u00f3digo, facilitando a manuten\u00e7\u00e3o e evitando erros.<\/li>\n\n\n\n
      3. Hacks Tempor\u00e1rios<\/strong>: Quando um hack ou uma solu\u00e7\u00e3o tempor\u00e1ria \u00e9 implementada, \u00e9 importante adicionar um coment\u00e1rio explicando o motivo e, se poss\u00edvel, um lembrete para refatorar ou revisar essa parte do c\u00f3digo posteriormente.<\/li>\n\n\n\n
      4. Assun\u00e7\u00f5es e Depend\u00eancias<\/strong>: Coment\u00e1rios s\u00e3o \u00fateis para documentar assun\u00e7\u00f5es feitas durante a implementa\u00e7\u00e3o e depend\u00eancias espec\u00edficas que n\u00e3o s\u00e3o \u00f3bvias apenas pela leitura do c\u00f3digo.<\/li>\n<\/ol>\n\n\n\n
        Vantagens dos Coment\u00e1rios Eficientes<\/h5>\n\n\n\n
          \n
        1. Clareza de Inten\u00e7\u00e3o<\/strong>: Coment\u00e1rios eficientes ajudam a explicar a inten\u00e7\u00e3o por tr\u00e1s do c\u00f3digo, tornando mais f\u00e1cil para outros desenvolvedores entenderem o prop\u00f3sito de um bloco de c\u00f3digo espec\u00edfico.<\/li>\n\n\n\n
        2. Contexto Adicional<\/strong>: Eles fornecem contexto adicional que pode n\u00e3o ser \u00f3bvio apenas pela leitura do c\u00f3digo, como o motivo de certas decis\u00f5es de design.<\/li>\n\n\n\n
        3. Facilitam a Manuten\u00e7\u00e3o<\/strong>: Coment\u00e1rios claros e atualizados tornam a manuten\u00e7\u00e3o do c\u00f3digo mais f\u00e1cil, pois os desenvolvedores podem entender rapidamente o que o c\u00f3digo faz e por que foi escrito daquela forma.<\/li>\n\n\n\n
        4. Melhoram a Documenta\u00e7\u00e3o<\/strong>: Coment\u00e1rios podem servir como uma forma de documenta\u00e7\u00e3o embutida, ajudando a manter o conhecimento sobre o sistema diretamente no c\u00f3digo.<\/li>\n<\/ol>\n\n\n\n
          Implementa\u00e7\u00e3o de Coment\u00e1rios Eficientes<\/h5>\n\n\n\n
            \n
          1. Comentar o “Porqu\u00ea”, N\u00e3o o “Como”<\/strong>: Explique o racioc\u00ednio por tr\u00e1s do c\u00f3digo, n\u00e3o apenas o que o c\u00f3digo faz. O c\u00f3digo j\u00e1 deve ser claro o suficiente para explicar “como” ele faz algo. Por exemplo, em vez de comentar “\/\/ incrementa contador”, um coment\u00e1rio eficiente seria “\/\/ incrementa contador para rastrear o n\u00famero de tentativas de login falhadas”.<\/li>\n\n\n\n
          2. Manter Coment\u00e1rios Atualizados<\/strong>: Coment\u00e1rios desatualizados podem ser mais prejudiciais do que a aus\u00eancia de coment\u00e1rios. Certifique-se de atualizar os coment\u00e1rios sempre que o c\u00f3digo mudar. Coment\u00e1rios desatualizados podem enganar desenvolvedores e levar a mal-entendidos e bugs.<\/li>\n\n\n\n
          3. Evitar Coment\u00e1rios \u00d3bvios<\/strong>: Coment\u00e1rios que simplesmente descrevem o que o c\u00f3digo faz s\u00e3o desnecess\u00e1rios e podem ser evitados. Foque em explicar l\u00f3gica complexa ou decis\u00f5es de design n\u00e3o triviais. Por exemplo, um coment\u00e1rio como “\/\/ define x para 5” \u00e9 redundante e desnecess\u00e1rio.<\/li>\n\n\n\n
          4. Ser Claro e Conciso<\/strong>: Coment\u00e1rios devem ser claros e diretos ao ponto. Evite escrever longos par\u00e1grafos quando uma frase curta pode ser suficiente. A clareza e a brevidade ajudam a garantir que os coment\u00e1rios sejam lidos e compreendidos.<\/li>\n\n\n\n
          5. Usar Coment\u00e1rios para Documentar Regras de Neg\u00f3cio<\/strong>: Utilize coment\u00e1rios para documentar regras de neg\u00f3cio importantes que s\u00e3o implementadas no c\u00f3digo. Isso ajuda a manter o entendimento do dom\u00ednio diretamente no c\u00f3digo, como em “\/\/ Aplica um desconto se o total da compra for maior que 1000, conforme definido pelo departamento de vendas”.<\/li>\n\n\n\n
          6. Adicionar “TODO” para Melhorias Futuras<\/strong>: Use coment\u00e1rios para marcar partes do c\u00f3digo que precisam de melhorias futuras ou refatora\u00e7\u00e3o com a tag “TODO”. Isso serve como um lembrete vis\u00edvel para desenvolvedores futuros.<\/li>\n<\/ol>\n\n\n\n
            \"\"<\/a><\/figure>\n\n\n\n
            Exemplos de Coment\u00e1rios Eficientes<\/h5>\n\n\n\n
              \n
            1. Explica\u00e7\u00e3o de Decis\u00f5es de Design<\/strong><\/li>\n<\/ol>\n\n\n\n

              Antes<\/strong><\/p>\n\n\n\n

              \/\/ Incrementa o contador\ncontador := contador + 1;\n<\/pre><\/div>\n\n\n\n
              Depois<\/strong><\/p>\n\n\n\n
              \/\/ Incrementa o contador para rastrear o n\u00famero de tentativas de login falhadas\ncontador := contador + 1;\n<\/pre><\/div>\n\n\n\n
              Um outro exemplo:<\/p>\n\n\n\n
              Antes<\/strong><\/p>\n\n\n\n
              \/\/ Verifica se o usu\u00e1rio \u00e9 um administrador\nif usuario.Role = 'admin' then\nbegin\n  \/\/ Permitir acesso\nend;\n<\/pre><\/div>\n\n\n\n
              Depois<\/strong><\/p>\n\n\n\n
              \/\/ Verifica se o usu\u00e1rio \u00e9 um administrador\n\/\/ Apenas administradores t\u00eam permiss\u00e3o para acessar esta se\u00e7\u00e3o sens\u00edvel do sistema\nif usuario.Role = 'admin' then\nbegin\n  \/\/ Permitir acesso\nend;\n<\/pre><\/div>\n\n\n\n
              Parece bobo, mas perceba que no primeiro exemplo \u00e9 bastante \u00f3bvio que \u00e9 um incremento de contador, entretanto ao ver o coment\u00e1rio atualizado, percebemos que \u00e9 um prop\u00f3sito no coment\u00e1rio, explicar o porque da vari\u00e1vel e seu incremento.<\/p>\n\n\n\n
              No segundo exemplo tempos uma situa\u00e7\u00e3o semelhamente. Percebemos claramente que o sistema est\u00e1 validando se o usu\u00e1rio \u00e9 um administrador, ok, mas por qu\u00ea? Na atualiza\u00e7\u00e3o entendemos que h\u00e1 um motivo para isso acontecer. <\/p>\n\n\n\n
              3. Documenta\u00e7\u00e3o de Regras de Neg\u00f3cio<\/p>\n\n\n\n
              No exemplo a seguir, implementamos um coment\u00e1rio que explica o porque da condicional if total > 1000 then<\/code>, e que adicona maior clareza.<\/p>\n\n\n\n
              Antes<\/strong><\/p>\n\n\n\n
              if total > 1000 then\nbegin\n  AplicarDesconto;\nend;\n<\/pre><\/div>\n\n\n\n
              Depois<\/strong><\/p>\n\n\n\n
              \/\/ Aplica um desconto se o total da compra for maior que 1000\n\/\/ Esta regra de neg\u00f3cio foi definida pelo departamento de vendas para incentivar compras maiores\nif total > 1000 then\nbegin\n  AplicarDesconto;\nend;\n<\/pre><\/div>\n\n\n\n
              Enfim, n\u00e3o \u00e9 proibido adicionar coment\u00e1rios ao c\u00f3digo, mas o desenvolvedor precisa focar em dois pontos:<\/p>\n\n\n\n
                \n
              1. Criar c\u00f3digos cada vez mais claros que n\u00e3o exijam a presen\u00e7a de um coment\u00e1rio.<\/li>\n\n\n\n
              2. Na impossibilidade, que o coment\u00e1rio seja realmente necess\u00e1rio e claro.<\/li>\n<\/ol>\n\n\n\n
                Conclus\u00e3o<\/h4>\n\n\n\n
                Coment\u00e1rios eficientes s\u00e3o uma parte vital do c\u00f3digo-limpo. Eles fornecem clareza, contexto e ajudam a documentar o racioc\u00ednio por tr\u00e1s do c\u00f3digo. Ao implementar coment\u00e1rios eficientes, os desenvolvedores podem melhorar significativamente a legibilidade e a manutenibilidade do c\u00f3digo, facilitando a colabora\u00e7\u00e3o e garantindo que o conhecimento sobre o sistema seja preservado. Investir tempo para escrever bons coment\u00e1rios \u00e9 uma pr\u00e1tica que paga dividendos a longo prazo, resultando em um c\u00f3digo mais robusto e sustent\u00e1vel. No pr\u00f3ximo artigo, exploraremos o quarto pilar do c\u00f3digo-limpo: Formata\u00e7\u00e3o Consistente.<\/p>\n\n\n\n
                Comunidade no Telegram<\/a><\/p>\n\n\n\n
                \ud83d\ude80Comente no campo abaixo \ud83d\udc47\ud83d\udc47\ud83d\udc47 o que achou e qual sua d\u00favida.<\/p>\n\n\n\n
                Te vejo na pr\u00f3xima<\/p>\n\n\n\n
                Adriano Santos<\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n\n\n\n
                <\/p>\n","protected":false},"excerpt":{"rendered":"
                Coment\u00e1rios no c\u00f3digo s\u00e3o ferramentas poderosas para desenvolvedores. Eles ajudam a esclarecer a l\u00f3gica, documentar decis\u00f5es e fornecer contexto adicional que n\u00e3o \u00e9 imediatamente evidente apenas pela leitura do c\u00f3digo. No entanto, a utiliza\u00e7\u00e3o de coment\u00e1rios deve ser feita com cautela e de forma estrat\u00e9gica para evitar problemas como a duplica\u00e7\u00e3o de informa\u00e7\u00e3o ou desatualiza\u00e7\u00e3o. […]<\/p>\n","protected":false},"author":1,"featured_media":730,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[47,45,14,37],"class_list":["post-725","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog","tag-inovacao","tag-programacao-2","tag-delphi","tag-dev"],"_links":{"self":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/725","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/comments?post=725"}],"version-history":[{"count":3,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/725\/revisions"}],"predecessor-version":[{"id":728,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/725\/revisions\/728"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media\/730"}],"wp:attachment":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media?parent=725"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/categories?post=725"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/tags?post=725"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}