Aunque los comentarios est\u00e1n principalmente destinados a los desarrolladores<\/a>, escribir unos comentarios eficaces tambi\u00e9n puede ayudar a elaborar una excelente documentaci\u00f3n para los usuarios de tu c\u00f3digo. Con la ayuda de generadores de documentos como Sphinx<\/a> para proyectos Python, los comentarios en tu c\u00f3digo pueden proporcionar contenido para tu documentaci\u00f3n.<\/p>\n Echemos un vistazo al funcionamiento de los comentarios en Python.<\/p>\n Seg\u00fan la Gu\u00eda de Estilo Python PEP 8<\/a>, hay varias cosas que debes tener en cuenta al escribir comentarios:<\/p>\n En Python, una l\u00ednea se declara comentario cuando comienza con el s\u00edmbolo Los comentarios inline proporcionan descripciones breves de variables y operaciones sencillas, y se escriben en la misma l\u00ednea que la sentencia del c\u00f3digo:<\/p>\n El comentario explica la funci\u00f3n del c\u00f3digo en la misma declaraci\u00f3n que el c\u00f3digo.<\/p>\n Los comentarios block se utilizan para describir la l\u00f3gica compleja del c\u00f3digo. Los comentarios block en Python se construyen de forma similar a los comentarios inline, la \u00fanica diferencia es que los comentarios block se escriben en una l\u00ednea aparte:<\/p>\n Ten en cuenta que cuando se utilizan comentarios block, los comentarios se escriben por encima del c\u00f3digo que est\u00e1n explicando. La Gu\u00eda de Estilo Python PEP8 dicta que una l\u00ednea de c\u00f3digo no debe contener m\u00e1s de setenta y nueve caracteres, y los comentarios inline a menudo sobrepasan esta longitud. Por eso los comentarios block se escriben para describir el c\u00f3digo en l\u00edneas separadas.<\/p>\n Python no admite de forma nativa los comentarios multil\u00ednea, lo que significa que no hay ninguna disposici\u00f3n especial para definirlos. A pesar de ello, a menudo se utilizan comentarios que abarcan varias l\u00edneas.<\/p>\n Puedes crear un comentario multil\u00ednea a partir de varios comentarios de una sola l\u00ednea precediendo cada l\u00ednea con Tambi\u00e9n puedes utilizar la sintaxis de cadenas multil\u00ednea. En Python, puedes definir cadenas de varias l\u00edneas encerr\u00e1ndolas entre En el c\u00f3digo anterior, la cadena multil\u00ednea no se asigna a una variable, lo que hace que la cadena funcione como un comentario. En tiempo de ejecuci\u00f3n, Python ignora la cadena, y no se incluye en el c\u00f3digo de bytes. La ejecuci\u00f3n del c\u00f3digo anterior produce la siguiente salida:<\/p>\n Adem\u00e1s de hacer que tu c\u00f3digo sea legible, los comentarios tambi\u00e9n sirven para algunos prop\u00f3sitos especiales en Python, como planificar futuras adiciones de c\u00f3digo y generar documentaci\u00f3n.<\/p>\n En Python, los docstrings son comentarios de varias l\u00edneas que explican c\u00f3mo utilizar una determinada funci\u00f3n o clase. La documentaci\u00f3n de tu c\u00f3digo mejora con la creaci\u00f3n de docstrings de alta calidad. Mientras trabajas con una funci\u00f3n o clase y utilizas la funci\u00f3n incorporada Python PEP 257<\/a> proporciona un m\u00e9todo est\u00e1ndar para declarar docstrings en Python, que se muestra a continuaci\u00f3n:<\/p>\n En el c\u00f3digo anterior, la docstring proporcionaba detalles sobre c\u00f3mo funciona la funci\u00f3n asociada. Con generadores de documentaci\u00f3n como Sphinx, esta docstring puede utilizarse para dar a los usuarios de tu proyecto una visi\u00f3n general de c\u00f3mo utilizar este m\u00e9todo.<\/p>\n Tambi\u00e9n se puede devolver una docstring definida justo debajo de la firma de la funci\u00f3n o clase utilizando la funci\u00f3n incorporada La llamada a la funci\u00f3n El atributo Al escribir c\u00f3digo, hay ocasiones en las que debes resaltar ciertas l\u00edneas o bloques enteros para mejorarlos. Estas tareas se marcan con comentarios TODO. Los comentarios TODO resultan \u00fatiles cuando planeas actualizaciones o cambios en tu c\u00f3digo, o si deseas informar a los usuarios o colaboradores del proyecto de que quedan por escribir secciones espec\u00edficas del c\u00f3digo del archivo.<\/p>\n Los comentarios TODO no deben escribirse como pseudoc\u00f3digo: s\u00f3lo tienen que explicar brevemente la funci\u00f3n del c\u00f3digo a\u00fan no escrito.<\/p>\n Los comentarios TODO y los comentarios block de una sola l\u00ednea son muy similares, y la \u00fanica diferencia entre ellos es que los comentarios TODO deben comenzar con un prefijo TODO:<\/p>\n Es importante se\u00f1alar que, aunque muchos IDE pueden resaltar estos comentarios para el programador, el int\u00e9rprete de Python no ve los comentarios TODO de forma diferente a los comentarios block.<\/p>\n Hay una serie de buenas pr\u00e1cticas que se deben seguir al escribir comentarios para garantizar su fiabilidad y calidad. A continuaci\u00f3n encontrar\u00e1s algunos consejos para escribir comentarios de alta calidad en Python.<\/p>\n Los comentarios que afirman lo obvio no a\u00f1aden ning\u00fan valor a tu c\u00f3digo, y deben evitarse. Por ejemplo<\/p>\n Ese comentario no es \u00fatil, ya que simplemente afirma lo que hace el c\u00f3digo sin explicar por qu\u00e9 hay que hacerlo. Los comentarios deben explicar el \u00abpor qu\u00e9\u00bb m\u00e1s que el \u00abqu\u00e9\u00bb del c\u00f3digo que describen.<\/p>\n Reescrito de forma m\u00e1s \u00fatil, el ejemplo anterior podr\u00eda tener este aspecto:<\/p>\n Los comentarios deben ser breves y f\u00e1ciles de entender. Deben estar escritos en prosa est\u00e1ndar, no en pseudoc\u00f3digo, y deben sustituir la necesidad de leer el c\u00f3digo real para obtener una visi\u00f3n general de lo que hace. Demasiados detalles o comentarios complejos no facilitan el trabajo del programador. Por ejemplo:<\/p>\n El comentario anterior proporciona m\u00e1s informaci\u00f3n de la necesaria para el lector. En lugar de especificar la l\u00f3gica central, los comentarios deben proporcionar un resumen general del c\u00f3digo. Este comentario puede reescribirse como<\/p>\n Los identificadores deben utilizarse con cuidado en los comentarios. Cambiar los nombres o los casos de los identificadores puede confundir al lector. Ejemplo:<\/p>\n El comentario anterior menciona Cuando escribes c\u00f3digo, debes adherirte al principio DRY (no repetirte) y evitar WET (escribir todo dos veces).<\/p>\n Esto tambi\u00e9n es v\u00e1lido para los comentarios. Evita utilizar varias sentencias para describir tu c\u00f3digo, e intenta fusionar comentarios que expliquen el mismo c\u00f3digo en un \u00fanico comentario. Sin embargo, es importante que tengas cuidado al fusionar comentarios: la fusi\u00f3n descuidada de varios comentarios puede dar lugar a un comentario enorme que infrinja las gu\u00edas de estilo y sea dif\u00edcil de seguir para el lector.<\/p>\n Recuerda que los comentarios deben reducir el tiempo de lectura del c\u00f3digo.<\/p>\n En el c\u00f3digo anterior, los comentarios est\u00e1n innecesariamente fragmentados, y pueden fusionarse en un \u00fanico comentario:<\/p>\n Aseg\u00farate de que los comentarios tienen la misma sangr\u00eda que el c\u00f3digo que describen. De lo contrario, puede resultar dif\u00edcil seguirlos.<\/p>\n Por ejemplo, este comentario no tiene la sangr\u00eda ni la posici\u00f3n adecuadas:<\/p>\n Puede reescribirse como sigue:<\/p>\n Los comentarios son un componente importante para escribir c\u00f3digo comprensible. La inversi\u00f3n que haces al escribir un comentario es algo que tu futuro yo \u2014 u otros desarrolladores que necesiten trabajar en tu base de c\u00f3digo \u2014 agradecer\u00e1n. Comentar tambi\u00e9n te permite obtener una visi\u00f3n m\u00e1s profunda de tu c\u00f3digo.<\/p>\n En este tutorial, has aprendido m\u00e1s sobre los comentarios en Python, incluidos los distintos tipos de comentarios en Python, cu\u00e1ndo utilizar cada uno de ellos y las mejores pr\u00e1cticas a seguir al crearlos.<\/p>\n Escribir buenos comentarios es una habilidad que hay que estudiar y desarrollar. Para practicar la escritura de comentarios, considera la posibilidad de volver atr\u00e1s y a\u00f1adir comentarios a algunos de tus proyectos anteriores. Para inspirarte y ver las mejores pr\u00e1cticas en acci\u00f3n, consulta proyectos Python bien documentados en GitHub.<\/p>\n Cuando est\u00e9s listo para poner en marcha tus propios proyectos Python, la plataforma de Alojamiento de Aplicaciones<\/a> de Kinsta puede llevar tu c\u00f3digo de GitHub a la nube<\/a> en cuesti\u00f3n de segundos.<\/p>\n","protected":false},"excerpt":{"rendered":" Los comentarios son notas que los programadores a\u00f1aden a su c\u00f3digo para explicar lo que se supone que debe hacer ese c\u00f3digo. Los compiladores o int\u00e9rpretes …<\/p>\n","protected":false},"author":275,"featured_media":61624,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_kinsta_gated_content":false,"_kinsta_gated_content_redirect":"","footnotes":""},"tags":[],"topic":[1320],"class_list":["post-61592","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","topic-python"],"yoast_head":"\nComentarios en Python<\/h2>\n
\n
#<\/code>. Cuando el int\u00e9rprete de Python encuentra #<\/code> en tu c\u00f3digo, ignora todo lo que hay despu\u00e9s de ese s\u00edmbolo y no produce ning\u00fan error. Hay dos formas de declarar comentarios de una sola l\u00ednea: comentarios inline y comentarios de bloque.<\/p>\nComentarios Inline<\/h3>\n
border = x + 10 # Make offset of 10px<\/code><\/pre>\nComentarios Block<\/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>\nComentarios Multil\u00ednea<\/h3>\n
#<\/code>:<\/p>\n# interpreter \n# ignores\n# these lines<\/code><\/pre>\n\"\"\"<\/code>, comillas dobles triples, o '''<\/code>, comillas simples triples:<\/p>\nprint(\"Multi-Line Comment\")\n\"\"\"\nThis\nString is \nMulti line \n\"\"\"<\/code><\/pre>\nMulti-Line Comment<\/code><\/pre>\n\nComentarios Especiales<\/h2>\n
Comentarios Docstring de Python<\/h3>\n
help(obj)<\/code>, los docstrings pueden ser \u00fatiles para dar una visi\u00f3n general del 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>. La funci\u00f3n help()<\/code> toma como argumento el nombre de un objeto o funci\u00f3n, y devuelve como salida las docstrings de la funci\u00f3n. En el ejemplo anterior, se puede llamar a help(get_person)<\/code> para mostrar los docstrings asociados a la funci\u00f3n get_person<\/code>. Si ejecutas el c\u00f3digo anterior en un int\u00e9rprete de comandos interactivo utilizando la bandera -i<\/code>, podr\u00e1s ver c\u00f3mo Python analiza esta cadena de documentos. Ejecuta el c\u00f3digo anterior escribiendo python -i file.py<\/code>.<\/p>\n![\"Captura](\"https:\/\/kinsta.com\/wp-content\/uploads\/2022\/12\/parsing-python-docstrings-on-command-line.png\")
help(get_person)<\/code> devuelve un docstring para tu funci\u00f3n. La salida contiene get_person(name, age, d=False)<\/code>, que es una firma de funci\u00f3n que Python a\u00f1ade autom\u00e1ticamente.<\/p>\nget_person.__ doc__<\/code> tambi\u00e9n puede utilizarse para recuperar y modificar docstrings mediante programaci\u00f3n. Despu\u00e9s de a\u00f1adir \u00abAlgo m\u00e1s de informaci\u00f3n nueva\u00bb en el ejemplo anterior, aparece en la segunda llamada a help(get_person)<\/code>. A\u00fan as\u00ed, es poco probable que necesites modificar din\u00e1micamente los docstrings en tiempo de ejecuci\u00f3n de esta forma.<\/p>\nComentarios 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>\nBuenas Pr\u00e1cticas al Escribir Comentarios en Python<\/h2>\n
Evita lo Obvio<\/h3>\n
x = x + 4 # increase x by 4<\/code><\/pre>\nx = x + 4 # increase the border width<\/code><\/pre>\nLos Comentarios de Python deben ser Breves y F\u00e1ciles de Entender<\/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>\nUtiliza los Identificadores con Cuidado<\/h3>\n
# return class() after modifying argument\ndef func(cls, arg):\n return cls(arg+5)\n<\/code><\/pre>\nclass<\/code> y argument<\/code>, ninguno de los cuales se encuentra en el c\u00f3digo. Este comentario puede reescribirse como<\/p>\n# return cls() after modifying arg\ndef func(cls, arg):\n return cls(arg+5)<\/code><\/pre>\nDRY y 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')\n<\/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')\n<\/code><\/pre>\nSangr\u00eda Coherente<\/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\nResumen<\/h2>\n