Comentar el c贸digo de Python

    La programaci贸n refleja su forma de pensar para describir los pasos individuales que sigui贸 para resolver un problema utilizando una computadora. Comentar su c贸digo ayuda a explicar su proceso de pensamiento y le ayuda a usted y a otros a comprender m谩s adelante la intenci贸n de su c贸digo. Esto le permite encontrar errores m谩s f谩cilmente, corregirlos, mejorar el c贸digo m谩s adelante y reutilizarlo tambi茅n en otras aplicaciones.

    Comentar es importante para todo tipo de proyectos, sin importar si son peque帽os, medianos o bastante grandes. Es una parte esencial de su flujo de trabajo y se considera una buena pr谩ctica para los desarrolladores. Sin comentarios, las cosas pueden volverse confusas, muy r谩pido. En este art铆culo, explicaremos los diversos m茅todos de comentarios que admite Python y c贸mo se puede utilizar para crear autom谩ticamente documentaci贸n para su c贸digo utilizando las denominadas cadenas de documentaci贸n a nivel de m贸dulo.

    Comentarios buenos y malos

    Por importantes que sean los comentarios, a煤n es posible escribir comentarios negativos. Siempre deben ser breves, ir al grano y agregar valor informativo.

    Por ejemplo, este es un comentario bastante in煤til:

    b = 56                       # assigning b a value of 56
    

    El siguiente ejemplo muestra un comentario m谩s 煤til, en cambio, y sigue dando a las variables nombres obvios:

    salestax10 = 1.10            # defining a sales tax of 10%
    salestax20 = 1.20            # defining a sales tax of 20%
    

    Hay un n煤mero infinito de otros escenarios que merecen comentarios. Esto es s贸lo un ejemplo. Una buena regla general ser铆a agregar comentarios para cualquier l铆nea de c贸digo (como una lista de comprensi贸n) o secci贸n de c贸digo cuyo prop贸sito no sea obvio. Esto es muy subjetivo y en realidad es una habilidad que debe aprenderse.

    Tipos de comentarios

    Un comentario en Python comienza con el car谩cter hash, #y se extiende hasta el final de la l铆nea f铆sica. Sin embargo, un car谩cter hash dentro de un valor de cadena no se considera un comentario. Para ser precisos, un comentario se puede escribir de tres maneras: completamente en su propia l铆nea, junto a una declaraci贸n de c贸digo y como un bloque de comentarios de varias l铆neas.

    En las siguientes secciones describir茅 cada tipo de comentario.

    Comentarios de una sola l铆nea

    Dicho comentario comienza con un car谩cter hash (#) y va seguido de un texto que contiene m谩s explicaciones.

    # defining the post code
    postCode = 75000
    

    Tambi茅n puede escribir un comentario junto a una declaraci贸n de c贸digo. El siguiente ejemplo muestra que:

    # define the general structure of the product with default values
    product = {
        "productId": 0,          # product reference id, default: 0
        "description": "",       # item description, default: empty
        "categoryId": 0,         # item category, default: 0
        "price": 0.00            # price, default: 0.00
    }
    

    La gu铆a de estilo para c贸digo Python (PEP8) recomienda menos de 79 caracteres por l铆nea. En la pr谩ctica, 70 o 72 caracteres por l铆nea son m谩s f谩ciles de leer, por lo que se recomienda. Si su comentario se acerca o excede esta longitud, entonces querr谩 distribuirlo en varias l铆neas.

    Comentarios de varias l铆neas

    Como ya se mencion贸 anteriormente, Python tambi茅n entiende un bloque de comentarios completo. Estos comentarios sirven como documentaci贸n en l铆nea para otros que leen su c贸digo y, por lo general, explican las cosas con m谩s detalle.

    T茅cnicamente, Python no tiene soporte expl铆cito para comentarios de varias l铆neas, por lo que algunas personas consideran que las siguientes opciones son una soluci贸n alternativa, pero a煤n funcionan para los comentarios de varias l铆neas.

    La versi贸n 1 combina comentarios de una sola l铆nea de la siguiente manera:

    # LinuxThingy version 1.6.5
    #
    # Parameters:
    #
    # -t (--text): show the text interface
    # -h (--help): display this help
    

    La versi贸n 2 es m谩s simple que la versi贸n 1. Originalmente est谩 pensada para ser utilizada para crear documentaci贸n (ver m谩s sobre esto a continuaci贸n), pero tambi茅n se puede utilizar para comentarios de varias l铆neas.

    """
    LinuxThingy version 1.6.5
    
    Parameters:
    
    -t (--text): show the text interface
    -h (--help): display this help
    """
    

    Tenga en cuenta que la 煤ltima versi贸n debe incluirse entre comillas especiales (""") para trabajar, y no caracteres hash.

    Pr谩ctica com煤n

    Es bastante com煤n iniciar un archivo Python con algunas l铆neas de comentarios. Estas l铆neas contienen informaci贸n sobre el proyecto, el prop贸sito del archivo, el programador que lo desarroll贸 o ha trabajado en 茅l y la licencia de software que se utiliza para el c贸digo.

    Este fragmento se tom贸 de uno de los ejemplos que utilizo con fines de capacitaci贸n. El comentario comienza con la descripci贸n y va seguido del aviso de derechos de autor con mi nombre y el a帽o de publicaci贸n del c贸digo. A continuaci贸n, ver谩 que el c贸digo tiene una licencia p煤blica GNU (GPL). Para contactarme, tambi茅n se agrega mi direcci贸n de correo electr贸nico.

    # -----------------------------------------------------------
    # demonstrates how to write ms excel files using python-openpyxl
    #
    # (C) 2015 Frank Hofmann, Berlin, Germany
    # Released under GNU Public License (GPL)
    # email [email聽protected]
    # -----------------------------------------------------------
    

    Comentarios de la cadena de documentos

    Python tiene un concepto incorporado llamado docstrings, que es una excelente manera de asociar la documentaci贸n que ha escrito con m贸dulos, funciones, clases y m茅todos de Python. Se agrega una cadena de documentos como comentario justo debajo de la funci贸n, m贸dulo o encabezado del objeto, y describe lo que hace la funci贸n, m贸dulo u objeto. Se espera que siga estas reglas:

    • Una cadena de documentos es una sola l铆nea o un comentario de varias l铆neas. En el 煤ltimo caso, la primera l铆nea es una descripci贸n breve y despu茅s de la primera l铆nea sigue una l铆nea vac铆a.
    • Comience la cadena de documentos con una letra may煤scula y term铆nela con un punto.

    Este es un ejemplo b谩sico de c贸mo se ve:

    def add(value1, value2):
        """Calculate the sum of value1 and value2."""
        return value1 + value2
    

    En el sistema de ayuda interactiva de Python, la cadena de documentos est谩 disponible a trav茅s del __doc__ atributo.

    >>> print add.__doc__
    Calculate the sum of value1 and value2.
    

    Hay una serie de herramientas que generan autom谩ticamente documentaci贸n a partir de cadenas de documentos, como Doxygen, PyDoc, pdoc, y el autodoc extensi贸n para Sphinx. Te explicaremos c贸mo trabajar con ellos en un art铆culo de seguimiento.

    Conclusi贸n

    Escribir comentarios adecuados en su c贸digo Python no es tan complicado y solo necesita el poder de la resistencia. Nos ayuda a todos los que intentamos comprender su c贸digo, incluido usted mismo para cuando vuelva a visitar su c贸digo en una fecha posterior. Esperamos que los consejos que le hemos dado aqu铆 le faciliten la creaci贸n de mejores comentarios y documentaci贸n en su c贸digo.

     

    Etiquetas:

    Deja una respuesta

    Tu direcci贸n de correo electr贸nico no ser谩 publicada. Los campos obligatorios est谩n marcados con *