Escrever bons comentários em Python permitirá que outros desenvolvedores e testadores leiam e entendam seu código facilmente.
Código limpo com sintaxe consistente, nomenclatura descritiva de variáveis e recuo é como o primeiro livro, mais fácil de entender e manter.
Além disso, hoje em dia é menos comum que um indivíduo escreva o código completo de todo o aplicativo ou software; em vez disso, uma equipe ou grupo de pessoas trabalhará para o mesmo objetivo. Nesse caso, um código limpo e legível torna a colaboração mais simples e eficiente.
Os desenvolvedores e testadores sempre buscam implantar software livre de bugs na produção. Escrever código limpo e legível acelera esse processo, tornando a depuração mais simples e precisa. Embora você encontre alguns erros na produção, um código mais limpo é mais fácil de atualizar.
Mais importante ainda, o código limpo e legível dura mais porque o código permanece atualizado com o passar do tempo.
Finalmente, é crucial ter um código limpo e legível para criar software duradouro. Mas a questão é: como exatamente conseguimos isso? Bem, um método é usar comentários.
Não é frustrante quando você escreve o código inteiro para uma lógica complexa, mas no dia seguinte não consegue continuar de onde parou? Isso não acontece quando você escreve comentários.
Os comentários são uma linguagem humana que explica o que o código-fonte está fazendo. Você pode escrevê-los em qualquer idioma, de preferência inglês, já que é um idioma global.
Portanto, sempre que você voltar ao seu código-fonte depois de dias ou até anos, os comentários explicarão o que você escreveu uma vez.
Além disso, eles ajudam outros desenvolvedores a entender facilmente seu código. É por isso que o código escrito com comentários permanece para sempre, mesmo na ausência do seu autor.
Além disso, é muito comum haver conflitos ao lidar com diferentes linguagens de programação, principalmente quando se trabalha em equipe. É aí que os comentários vêm em socorro. Embora você não conheça a linguagem de programação do código-fonte escrito por seu colega de equipe, os comentários ajudam você a entender a lógica por trás dele.
A documentação do código é uma maneira mais abrangente de manter seu código-fonte e permite que sua equipe colabore perfeitamente. Ele contém tudo sobre o código, como design, funcionalidade, arquitetura, componentes, etc.,
Os comentários até contribuem para a documentação deste código. Comentários bem escritos podem ser incluídos diretamente na documentação do código para que os desenvolvedores não apenas obtenham o quê e o porquê, mas também o como do seu código.
- Os comentários não apenas leem o código, mas também ajudam você a entender a intenção do desenvolvedor por trás de cada linha. Portanto, se você encontrar algum bug no futuro, saberá exatamente onde fazer as atualizações do código.
- Você pode escrever comentários como um parágrafo para todo o código ou linhas individuais explicando o que cada bloco de código faz. Dessa forma, eles permitem que você e outros desenvolvedores entendam bem o código, melhorando a legibilidade.
- Os comentários podem dividir o código em seções lógicas, simplificando a navegação do código.
- Você deve incluir comentários detalhando entradas, saídas e casos de uso esperados para que um testador possa ler seu código.
- Finalmente, colocar comentários bem escritos na sua documentação melhora a legibilidade geral da documentação do código.
Os comentários em Python começam com um símbolo de hash (#). Portanto, quando você inicia uma linha com hash (#), qualquer coisa escrita nessa linha é tratada como um comentário.
Quando você executa o código, o compilador ignora a linha que começa com hash (#) como se ela nem existisse. No entanto, os comentários permanecem visíveis no código-fonte para servir ao seu propósito.
Existem três tipos principais.
Estes são os que você viu acima. Eles começam com o símbolo de hash (#). Basicamente, a linha que começa com o símbolo de hash (#) é dedicada ao comentário. Portanto, isso é chamado de comentário de linha única, onde você pode escrever um comentário apenas em uma linha começando com hash (#).
Veja como você pode escrever comentários de uma linha
# This is single line comment.
Tecnicamente, Python não suporta comentários multilinhas, mas existem maneiras de conseguir isso em Python.
Você também pode usar hash (#) para escrever comentários de várias linhas. Cada linha que você escreve deve começar com um símbolo de hash (#) aqui.
# This is the first comment. # This is second comment. # This is the last comment.
últimas postagens
#3. Documentos Python
Uma maneira popular de escrever comentários multilinhas é usar strings literais – “””….”””. Quando você escreve algo entre aspas triplas, o compilador Python ignora essas linhas e executa a parte restante do arquivo.
Esses comentários são chamados de docstrings quando escritos logo após as funções, módulos e classes.
Aqui está a sintaxe para fazer isso
""" Multi-line comments using docstrings in Python. """
Escrever comentários claros e detalhados melhora a legibilidade e a manutenção do código. Então, aqui estão as práticas recomendadas para comentários claros em Python.
Os comentários não devem apenas narrar o que o código está fazendo; em vez disso, devem refletir o propósito e a intenção por trás de cada linha.
Remova comentários desatualizados e certifique-se de atualizá-los sempre que modificar o código.
Em vez de histórias longas, escreva comentários curtos e objetivos.
Bad example: The function takes a,b as input, calculates a + b, and returns the value. Good example: The function returns the sum of a and b.
Usar nomes significativos e descritivos para variáveis e nomes de funções pode eliminar comentários redundantes.
Código primeiro? Ou comentar primeiro? Comentar antes de codificar é a prática recomendada; isto é, escreva seus comentários e depois o código correspondente. Dessa forma, você pode primeiro pensar na lógica e depois convertê-la em código.
# Returns true if the cnt is less than 1. return cnt < 1
Use um formato de comentário consistente, como espaçamento, recuo, tipo de comentários, etc., para todo o código. Isso será menos confuso e mais organizado para os leitores.
Use docstrings para explicar funções e classes em Python, conforme mostrado no exemplo a seguir.
def add_num(a,b):
""" this function returns the sum of a and b """
sum = a+b
return sum
Evite comentários desnecessários em seu código. Por exemplo, a linha de código a seguir não precisa de comentários para ser entendida.
ans = 42
#1. Editor de código do Visual Studio
Editor de código do Visual Studio é o melhor IDE desenvolvido pela Microsoft para um ambiente de desenvolvimento completo. Com suporte nativo para Node.js e JavaScript, a ferramenta também suporta muitas outras linguagens de programação perfeitamente.
Esta ferramenta altamente personalizável possui várias extensões para diferentes funcionalidades. ‘Better Comments’ é uma extensão que permite criar comentários amigáveis.
Você pode categorizar seus comentários em alertas, consultas, destaques, etc., para facilitar a navegação.
O código VS oferece suporte à edição com vários cursores para que você possa comentar ou editar várias linhas simultaneamente.
Este editor está disponível em todas as principais plataformas, como Mac, Windows e Linux.
#2. Texto sublime
Texto sublime é o editor ideal para grandes projetos e codificação pesada. O editor é conhecido por sua velocidade, personalização e atalhos.
O poderoso recurso de realce de sintaxe da ferramenta ajuda a distinguir facilmente entre o código e os comentários.
Assim como o código VS, o texto Sublime também oferece suporte à edição com vários cursores para comentar várias linhas ao mesmo tempo.
Graças ao seu recurso de preenchimento automático. Você não precisa repetir manualmente as linhas de código; esse recurso completa automaticamente seu código com base nos padrões, ajudando você a codificar mais rapidamente.
Além disso, o recurso ‘Goto Anything’ da ferramenta permite alternar perfeitamente entre as funções e arquivos do seu projeto.
#3. Bloco de notas++
Nodepad++ é um editor de texto simples e popular escrito em C++ e oferece suporte a inúmeras linguagens de programação. Não se parece com um editor moderno como VS Code ou Sublime Text; sua interface é muito simples e parece que faz o que precisa.
O Nodepad++ oferece vários atalhos padrão para comentários eficientes. Você também pode personalizar o teclado de atalho para personalizar sua experiência de comentários.
Seu recurso de mapa de documentos mostra uma visão geral da estrutura do projeto, permitindo navegar perfeitamente pelos arquivos, pastas e código.
#4. Vim
Vim IDE fornece desenvolvimento e execução de código mais rápidos. Tudo e mais alguma coisa pode ser feito neste editor usando atalhos de teclado, então você deve se esforçar muito para dominá-lo.
Este editor centrado no teclado também oferece muitos recursos de comentários por meio de atalhos de teclado. Possui recursos e comandos poderosos para navegar com eficácia pelos comentários.
Este software leve pode lidar com arquivos enormes e centenas de linguagens de programação. Quem odeia coisas grátis? Como todos os editores da lista, o Vim também é totalmente gratuito e de código aberto.
Ele vem nativo em sistemas macOS e Linux e pode ser baixado no Windows.
#5. PyCharm
PyCharm é um IDE poderoso especialmente projetado para desenvolvimento em Python. Embora suporte muitas outras linguagens de programação, funciona melhor para Python. Possui preenchimento de código, realce de sintaxe e recursos de depuração personalizados para Python.
Além disso, torna os comentários em Python muito mais eficientes. Ele fornece recursos de navegação para ajudá-lo a acessar comentários específicos facilmente.
Obtenha vários modelos de comentários e crie modelos de comentários personalizados de forma eficiente no Pycharm.
Além disso, as ferramentas de refatoração do editor permitem atualizar ou corrigir comentários facilmente.
Conclusão
Seguir os padrões de código é necessário durante todo o processo de desenvolvimento do código e obrigatório para escrever código pronto para produção, pois seu código deve ser legível por todos os outros desenvolvedores e testadores.
Uma prática importante para criar um código legível é escrever comentários. Os comentários estão disponíveis em quase todas as linguagens de programação. No entanto, com este artigo, agora você deve saber como escrever comentários em Python, seus tipos e as práticas recomendadas a serem seguidas ao escrever comentários.
Além disso, os melhores editores de código que ajudam no gerenciamento de comentários estão listados abaixo.