Embora os coment\u00e1rios sejam principalmente para os desenvolvedores<\/a>, escrever coment\u00e1rios eficazes tamb\u00e9m pode ajudar na produ\u00e7\u00e3o de excelente documenta\u00e7\u00e3o para os usu\u00e1rios do seu c\u00f3digo. Com a ajuda de geradores de documentos como o Sphinx<\/a> para projetos Python, coment\u00e1rios em seu c\u00f3digo podem fornecer conte\u00fado para sua documenta\u00e7\u00e3o.<\/p>\n Vamos dar uma olhada nos coment\u00e1rios no Python.<\/p>\n Conforme o\u00a0Guia de Estilo Python PEP 8<\/a>, h\u00e1 v\u00e1rias coisas para se ter em mente ao escrever coment\u00e1rios:<\/p>\n Em Python, uma linha \u00e9 declarada como um coment\u00e1rio quando come\u00e7a com o s\u00edmbolo Os coment\u00e1rios em linha fornecem pequenas descri\u00e7\u00f5es de vari\u00e1veis e opera\u00e7\u00f5es simples sendo escritos na mesma linha da declara\u00e7\u00e3o do c\u00f3digo:<\/p>\n O coment\u00e1rio explica a fun\u00e7\u00e3o do c\u00f3digo na mesma declara\u00e7\u00e3o que o c\u00f3digo.<\/p>\n Coment\u00e1rios em bloco s\u00e3o usados para descrever l\u00f3gica complexa no c\u00f3digo. Os coment\u00e1rios de bloco no Python s\u00e3o constru\u00eddos de forma similar aos coment\u00e1rios em linha – a \u00fanica diferen\u00e7a \u00e9 que os coment\u00e1rios de bloco s\u00e3o escritos em uma linha separada:<\/p>\n Note que ao usar coment\u00e1rios em bloco, os coment\u00e1rios s\u00e3o escritos acima do c\u00f3digo que eles est\u00e3o explicando. O Python PEP8 Style Guide dita que uma linha de c\u00f3digo n\u00e3o deve conter mais de setenta e nove caracteres, e os coment\u00e1rios em linha muitas vezes movem as linhas por esse comprimento. \u00c9 por isso que os coment\u00e1rios em bloco s\u00e3o escritos para descrever o c\u00f3digo em linhas separadas.<\/p>\n Python n\u00e3o suporta nativamente coment\u00e1rios de v\u00e1rias linhas, o que significa que n\u00e3o h\u00e1 nenhuma provis\u00e3o especial para defini-los. Apesar disso, coment\u00e1rios que abrangem v\u00e1rias linhas s\u00e3o frequentemente usados.<\/p>\n Voc\u00ea pode criar um coment\u00e1rio com v\u00e1rias linhas a partir de v\u00e1rios coment\u00e1rios de uma linha, prefixando cada linha com Voc\u00ea tamb\u00e9m pode usar a sintaxe de strings de caracteres de v\u00e1rias linhas. Em Python, voc\u00ea pode definir strings de caracteres com v\u00e1rias linhas, anexando em No c\u00f3digo acima, a string de m\u00faltiplas linhas n\u00e3o \u00e9 atribu\u00edda a uma vari\u00e1vel, o que faz com que a string funcione como um coment\u00e1rio. Em tempo de execu\u00e7\u00e3o, Python ignora a string, e ela n\u00e3o est\u00e1 inclu\u00edda no bytecode. A execu\u00e7\u00e3o do c\u00f3digo acima produz a seguinte sa\u00edda:<\/p>\n Al\u00e9m de tornar seu c\u00f3digo leg\u00edvel, os coment\u00e1rios tamb\u00e9m servem alguns prop\u00f3sitos especiais em Python, tais como planejar futuras adi\u00e7\u00f5es de c\u00f3digo e gerar documenta\u00e7\u00e3o.<\/p>\n Em Python, docstrings s\u00e3o coment\u00e1rios de v\u00e1rias linhas que explicam como usar uma determinada fun\u00e7\u00e3o ou classe. A documenta\u00e7\u00e3o do seu c\u00f3digo \u00e9 melhorada com a cria\u00e7\u00e3o de docstrings de alta qualidade. Ao trabalhar com uma fun\u00e7\u00e3o ou classe e usar a fun\u00e7\u00e3o Python PEP 257<\/a> fornece um m\u00e9todo padr\u00e3o de declara\u00e7\u00e3o de documentos em Python, mostrado abaixo:<\/p>\n No c\u00f3digo acima, a docstring forneceu detalhes sobre como a fun\u00e7\u00e3o associada funciona. Com geradores de documenta\u00e7\u00e3o como o Sphinx, esta docstring pode ser usada para dar aos usu\u00e1rios do seu projeto uma vis\u00e3o geral de como usar este m\u00e9todo.<\/p>\n Um docstring definido logo abaixo da fun\u00e7\u00e3o ou assinatura de classe tamb\u00e9m pode ser retornado usando a fun\u00e7\u00e3o A chamada de fun\u00e7\u00e3o O atributo Ao escrever c\u00f3digo, h\u00e1 ocasi\u00f5es em que voc\u00ea vai querer destacar certas linhas ou blocos inteiros para melhorar. Estas tarefas s\u00e3o marcadas pelos coment\u00e1rios do TODO. Coment\u00e1rios TODO s\u00e3o \u00fateis quando voc\u00ea est\u00e1 planejando atualiza\u00e7\u00f5es ou mudan\u00e7as no seu c\u00f3digo, ou se voc\u00ea deseja informar aos usu\u00e1rios ou colaboradores do projeto que se\u00e7\u00f5es espec\u00edficas do c\u00f3digo do arquivo ainda est\u00e3o para ser escritas.<\/p>\n Os coment\u00e1rios TODO n\u00e3o devem ser escritos como pseudoc\u00f3digo – eles apenas t\u00eam que explicar brevemente a fun\u00e7\u00e3o do c\u00f3digo ainda n\u00e3o escrito.<\/p>\n Coment\u00e1rios TODO e coment\u00e1rios de bloco de uma linha s\u00e3o muito semelhantes, e a \u00fanica distin\u00e7\u00e3o entre eles \u00e9 que os coment\u00e1rios TODO devem come\u00e7ar com um prefixo TODO:<\/p>\n \u00c9 importante notar que embora muitas IDEs possam destacar estes coment\u00e1rios para o programador, o int\u00e9rprete Python n\u00e3o v\u00ea os coment\u00e1rios TODO de forma diferente dos coment\u00e1rios de bloco.<\/p>\n H\u00e1 uma s\u00e9rie de melhores pr\u00e1ticas que devem ser seguidas ao escrever coment\u00e1rios para garantir confiabilidade e qualidade. Abaixo est\u00e3o algumas dicas para escrever coment\u00e1rios de alta qualidade em Python.<\/p>\n Coment\u00e1rios que afirmam o \u00f3bvio, n\u00e3o agregam nenhum valor ao seu c\u00f3digo, e devem ser evitados. Por exemplo:<\/p>\n Esse coment\u00e1rio n\u00e3o \u00e9 \u00fatil, j\u00e1 que simplesmente declara o que o c\u00f3digo faz sem explicar porque ele precisa ser feito. Os coment\u00e1rios devem explicar o “por que” ao inv\u00e9s do “o qu\u00ea” do c\u00f3digo que eles est\u00e3o descrevendo.<\/p>\n Reescrito de forma mais \u00fatil, o exemplo acima pode se parecer com este:<\/p>\n Mantenha seus coment\u00e1rios curtos e de f\u00e1cil compreens\u00e3o. Eles devem ser escritos em prosa padr\u00e3o, n\u00e3o em pseudo-c\u00f3digo, e devem substituir a necessidade de ler o c\u00f3digo real para obter uma vis\u00e3o geral do que ele faz. Demasiados detalhes ou coment\u00e1rios complexos n\u00e3o facilitam o trabalho de um programador. Por exemplo:<\/p>\n O coment\u00e1rio acima fornece mais informa\u00e7\u00f5es do que as necess\u00e1rias para o leitor. Ao inv\u00e9s de especificar a l\u00f3gica central, os coment\u00e1rios devem fornecer um resumo geral do c\u00f3digo. Este coment\u00e1rio pode ser reescrito como:<\/p>\n Os Identifiers devem ser usados cuidadosamente nos coment\u00e1rios. Mudar nomes de Identifiers ou casos pode confundir o leitor. Exemplo:<\/p>\n O coment\u00e1rio acima menciona Quando voc\u00ea est\u00e1 escrevendo c\u00f3digo, voc\u00ea quer aderir ao princ\u00edpio DRY (n\u00e3o se repita) e evitar WET (escreva tudo duas vezes).<\/p>\n Isso tamb\u00e9m se aplica aos coment\u00e1rios. Evite usar m\u00faltiplas declara\u00e7\u00f5es para descrever seu c\u00f3digo e tente fundir coment\u00e1rios que expliquem o mesmo c\u00f3digo em um \u00fanico coment\u00e1rio. Entretanto, \u00e9 importante ter cuidado quando voc\u00ea estiver mesclando coment\u00e1rios: a fus\u00e3o descuidada de m\u00faltiplos coment\u00e1rios pode resultar em um enorme coment\u00e1rio que viola os guias de estilo e \u00e9 dif\u00edcil para o leitor acompanhar.<\/p>\n Lembre-se que os coment\u00e1rios devem reduzir o tempo de leitura do c\u00f3digo.<\/p>\n No c\u00f3digo acima, os coment\u00e1rios s\u00e3o desnecessariamente fragmentados, e podem ser fundidos em um \u00fanico coment\u00e1rio:<\/p>\n Certifique-se de que os coment\u00e1rios sejam indentados no mesmo n\u00edvel do c\u00f3digo que eles est\u00e3o descrevendo. Quando n\u00e3o est\u00e3o, eles podem ser dif\u00edceis de seguir.<\/p>\n Por exemplo, este coment\u00e1rio n\u00e3o \u00e9 indentado ou posicionado corretamente:<\/p>\n Ela pode ser reescrita da seguinte forma:<\/p>\n Os coment\u00e1rios s\u00e3o um componente importante para escrever um c\u00f3digo compreens\u00edvel. O investimento que voc\u00ea faz ao escrever um coment\u00e1rio \u00e9 um investimento que seu futuro eu – ou outros desenvolvedores que precisam trabalhar na sua base de c\u00f3digo – ir\u00e1 apreciar. Comentar tamb\u00e9m permite que voc\u00ea obtenha insights mais detalhados sobre o seu c\u00f3digo.<\/p>\n Neste tutorial, voc\u00ea aprendeu mais sobre os coment\u00e1rios no Python, incluindo os v\u00e1rios tipos de coment\u00e1rios Python, quando usar cada um deles, e as melhores pr\u00e1ticas a seguir ao cri\u00e1-los.<\/p>\n Escrever bons coment\u00e1rios \u00e9 uma habilidade que precisa ser estudada e desenvolvida. Para praticar a escrita de coment\u00e1rios, considere voltar atr\u00e1s e adicionar coment\u00e1rios a alguns de seus projetos anteriores. Para inspira\u00e7\u00e3o e para ver as melhores pr\u00e1ticas em a\u00e7\u00e3o, confira os projetos bem documentados Python no GitHub.<\/p>\n Quando voc\u00ea estiver pronto para fazer seus pr\u00f3prios projetos Python em tempo real, a plataforma Hospedagem de Aplicativos da Kinsta<\/a> pode levar seu c\u00f3digo do GitHub para a nuvem<\/a> em segundos.<\/p>\n","protected":false},"excerpt":{"rendered":" Coment\u00e1rios s\u00e3o notas que os programadores postam no c\u00f3digo para explicar o que o c\u00f3digo deve fazer. Coment\u00e1rios s\u00e3o ignorados por compiladores ou interpretadores que transformam …<\/p>\n","protected":false},"author":275,"featured_media":56245,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kinsta_gated_content":false,"_kinsta_gated_content_redirect":"","footnotes":""},"tags":[],"topic":[1001],"class_list":["post-56244","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","topic-python"],"yoast_head":"\nComent\u00e1rios no Python<\/h2>\n
\n
#<\/code>. Quando o int\u00e9rprete Python encontra #<\/code> em seu c\u00f3digo, ele ignora qualquer coisa depois daquele s\u00edmbolo e n\u00e3o produz nenhum erro. H\u00e1 duas maneiras de declarar coment\u00e1rios de uma linha: coment\u00e1rios em linha e coment\u00e1rios em bloco.<\/p>\nComent\u00e1rios em linha<\/h3>\n
border = x + 10 # Make offset of 10px<\/code><\/pre>\nComent\u00e1rios em bloco<\/h3>\n
import csv\nfrom itertools import groupby\n\n# Get a list of names in a sequence from the csv file\nwith open('new-top-firstNames.csv') as f:\n file_csv = csv.reader(f)\n\n# Skip the header part: (sr, name, perc)\nheader = next(file_csv)\n \n# Only name from (number, name, perc)\npersons = [ x[1] for x in file_csv]\n\n# Sort the list by first letter because \n# The groupby function looks for sequential data.\npersons.sort(key=lambda x:x[0])\ndata = groupby(persons, key=lambda x:x[0])\n\n# Get every name as a list \ndata_grouped = {}\nfor k, v in data:\n # Get data in the form \n # {'A' : [\"Anthony\", \"Alex\"], \"B\" : [\"Benjamin\"]}\n data_grouped[k] = list(v)<\/code><\/pre>\nComent\u00e1rios em v\u00e1rias linhas<\/h3>\n
#<\/code>:<\/p>\n# interpreter \n# ignores\n# these lines<\/code><\/pre>\n\"\"\"<\/code>, aspas duplas triplas, ou '''<\/code>, aspas simples triplas:<\/p>\nprint(\"Multi-Line Comment\")\n\"\"\"\nThis\nString is \nMulti line \n\"\"\"<\/code><\/pre>\nMulti-Line Comment<\/code><\/pre>\n\nComent\u00e1rios especiais<\/h2>\n
Coment\u00e1rios no Python Docstring<\/h3>\n
help(obj)<\/code> integrada, a docstrings pode ser \u00fatil para dar uma vis\u00e3o geral do objeto.<\/p>\nfrom collections import namedtuple\nPerson = namedtuple('Person', ['name', 'age'])\n\n def get_person(name, age, d=False):\n \"\"\"\nReturns a namedtuple(\"name\", \"age\") object.\nAlso returns dict('name', 'age') if arg `d` is True\n\nArguments:\nname \u2013 first name, must be string\nage \u2013 age of person, must be int\nd \u2013 to return Person as `dict` (default=False)\n\n\"\"\"\np = Person(name, age)\nif d:\n return p._asdict()\nreturn p<\/code><\/pre>\nhelp()<\/code>. A fun\u00e7\u00e3o help()<\/code> toma um objeto ou nome de fun\u00e7\u00e3o como argumento, e retorna as docstrings da fun\u00e7\u00e3o como sa\u00edda. No exemplo acima, help(get_person)<\/code> pode ser chamado para revelar as docstrings associadas \u00e0 fun\u00e7\u00e3o get_person<\/code>. Se voc\u00ea executar o c\u00f3digo acima em uma shell interativa usando a flag -i<\/code>, voc\u00ea pode ver como este docstring ser\u00e1 analisado pelo Python. Execute o c\u00f3digo acima digitando python -i file.py<\/code>.<\/p>\n![\"Coment\u00e1rios](\"https:\/\/kinsta.com\/wp-content\/uploads\/2022\/12\/parsing-python-docstrings-on-command-line.png\")
help(get_person)<\/code> retorna um docstring para \u00e0 sua fun\u00e7\u00e3o. A sa\u00edda cont\u00e9m get_person(name, age, d=False)<\/code>, que \u00e9 uma assinatura de fun\u00e7\u00e3o que o Python adiciona automaticamente.<\/p>\nget_person.__ doc__<\/code> tamb\u00e9m pode ser usado para recuperar e modificar docstrings programmaticamente. Ap\u00f3s adicionar “Mais algumas informa\u00e7\u00f5es novas” no exemplo acima, ele aparece na segunda chamada para help(get_person)<\/code>. Ainda assim, \u00e9 improv\u00e1vel que voc\u00ea precise alterar a docstrings dinamicamente em tempo de execu\u00e7\u00e3o como este.<\/p>\nComent\u00e1rios TODO<\/h3>\n
# TODO Get serialized data from the CSV file\n# TODO Perform calculations on the data\n# TODO Return to the user<\/code><\/pre>\nMelhores pr\u00e1ticas ao escrever coment\u00e1rios no Python<\/h2>\n
Evite o \u00f3bvio<\/h3>\n
x = x + 4 # increase x by 4<\/code><\/pre>\nx = x + 4 # increase the border width<\/code><\/pre>\nMantenha os coment\u00e1rios curtos<\/h3>\n
# return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r)\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\n# return area of cylinder\ndef get_area(r,h):\n return (2*3.14*r*h) + (2*3.14*r*r)<\/code><\/pre>\nUse Identifiers cuidadosamente<\/h3>\n
# return class() after modifying argument\ndef func(cls, arg):\n return cls(arg+5)\n<\/code><\/pre>\nclass<\/code> e argument<\/code>, nenhum dos quais \u00e9 encontrado no c\u00f3digo. Este coment\u00e1rio pode ser reescrito como:<\/p>\n# return cls() after modifying arg\ndef func(cls, arg):\n return cls(arg+5)<\/code><\/pre>\nDRY e WET<\/h3>\n
\"># function to do x work\ndef do_something(y):\n # x work cannot be done if y is greater than max_limit\n if y < 400:\n print('doing x work')<\/code><\/pre>\n\"># function to do x if arg:y is less than max_limit\ndef do_something(y):\n if y in range(400):\n print('doing x work')<\/code><\/pre>\n<\/code><\/p>\nIndenta\u00e7\u00e3o Consistente<\/h3>\n
for i in range(2,20, 2):\n# only even numbers\n if verify(i):\n# i should be verified by verify()\n perform(x)<\/code><\/pre>\n# only even numbers\nfor i in range(2,20, 2):\n # i should be verified by verify()\n if verify(i):\n perform(x)<\/code><\/pre>\n\nResumo<\/h2>\n