Como fazer comentários no código em Python: um guia completa para iniciantes

Caro(a) leitor(a), se tu estás se perguntando se além de codar, você ainda deve comentar seu código, seja ele em python ou em qualquer outra linguagem, chegaste ao artigo certo! Quer saber como comentar seu código python de diferentes maneiras, quais são as melhores práticas e também exemplos práticos? Então esse artigo é pra ti! 😉

Por que fazer comentários em Python?

Muitas pessoas falam sobre a importância de comentar o código em todas as linguagens de programação, mas poucas explicam realmente o porquê. Vamos a um exemplo: imagine que você trabalha em uma empresa e seu líder pede para você adicionar uma nova função a um programa. O desafio é que esse código foi editado por mais de 30 desenvolvedores, passou por diversas atualizações e tem muitos aplicativos associados. Não seria mais fácil se o código estivesse bem documentado? Isso ajudaria você a entender rapidamente a estrutura e a localizar a função que precisa modificar.

Os comentários facilitam a manutenção do código. Quando um desenvolvedor retorna a um projeto após um tempo, os comentários ajudam a refrescar a memória sobre a lógica e as intenções por trás do código. Além disso, em equipes grandes, diferentes desenvolvedores podem trabalhar no mesmo código. Comentários garantem que todos compreendam a lógica e as decisões tomadas, reduzindo mal-entendidos. Outra função importante dos comentários é servir como documentação interna. Eles explicam como funções específicas funcionam, quais são seus parâmetros e o que retornam, sem a necessidade de consultar documentação externa. Porém, é preciso ter cuidado com comentários muito longos ou confusos, que podem acabar atrapalhando mais do que ajudando. A dica é: seja claro e objetivo, procurando ser o mais didático possível.

Como fazer um comentário em Python?

Em Python, você pode fazer comentários usando o símbolo # para comentários de linha única, por exemplo:

Programa que retorna a mensagem Olá, Mundo!

Programa para somar dois números

Programa que imprime uma lista de frutas

Como comentar várias linhas em Python?

Para comentar várias linhas em python você pode utilizar aspas triplas (simples ou duplas), veja um exemplo:

Comentários usando aspas simples

Comentários usando aspas duplas

Como comentar várias linhas no VSCode para Python?

Para comentar várias linhas no VSCode ao trabalhar com Python, você pode seguir estes passos:

• Selecione as linhas que deseja comentar com o mouse
• No Windows ou Linux: Pressione Ctrl + /
• No macOS: Pressione Cmd + /

Como comentar várias linhas no PyCharm para Python?

Para comentar várias linhas no PyCharm ao trabalhar com Python, você pode seguir estes passos:

• Selecione as linhas que deseja comentar com o mouse
• No Windows ou Linux: Pressione Ctrl + /
• No macOS: Pressione Cmd + /

Melhores práticas para comentários em Python

As práticas recomendadas podem variar de acordo com a documentação da sua empresa, mas aqui estão algumas dicas úteis que se aplicam a qualquer organização:

• Mantenha seus comentários curtos e diretos. Evite verbosidade desnecessária que pode desorganizar seu código 🙁
• Faça o esforço de sempre descrever o raciocínio por trás do que você escreveu, não apenas o que o código faz. Isso ajuda os leitores a entenderem seu processo de pensamento 😉
• Escolha nomes claros e descritivos para variáveis e funções, minimizando a necessidade de comentários excessivos ou longos;
• Lembre-se de revisar e atualizar os comentários conforme seu código evolui. Comentários desatualizados podem enganar os desenvolvedores, em vez de ajudar. 🤯

Conclusão

A partir de agora você já sabe: comentar o código é essencial para garantir que ele seja #compreensível e ‘’’fácil de manter’’’. Em projetos colaborativos, onde múltiplos desenvolvedores estão envolvidos, comentários claros ajudam a transmitir a intenção por trás de cada parte do código. Os comentários facilitam a compreensão do que a função faz, especialmente para quem não está familiarizado com a lógica. Além disso, é importante revisar e atualizar comentários à medida que o código evolui 🙂