{"id":5464,"date":"2018-08-02T13:55:51","date_gmt":"2018-08-02T18:55:51","guid":{"rendered":"https:\/\/islascruz.org\/blog\/?p=5464"},"modified":"2018-08-03T10:38:28","modified_gmt":"2018-08-03T15:38:28","slug":"documentando-codigo-en-python","status":"publish","type":"post","link":"https:\/\/islascruz.org\/blog\/2018\/08\/02\/documentando-codigo-en-python\/","title":{"rendered":"Documentando c\u00f3digo en Python"},"content":{"rendered":"

Code is more often read than written<\/p>\n

– Guido Van Rosssum<\/p><\/blockquote>\n

<\/p>\n

El c\u00f3digo es mas veces le\u00eddo que escrito, por eso es importante documentarlo apropiadamente. Un c\u00f3digo bien documentado permite a quien recibe el c\u00f3digo saber que hace dicho pedazo de c\u00f3digo, sea una funci\u00f3n, una clase, modulo o paquete.<\/p>\n

Quien recibe el c\u00f3digo puede ser tal vez un compa\u00f1ero de trabajo, puede ser alguien que no conozcas en absoluto o puedes ser tu mismo dentro de unos cuantos meses.<\/p>\n

\"r_820413_wyzyE\"<\/p>\n

Estoy seguro que no te ser\u00e1 extra\u00f1a la vez que viste un c\u00f3digo y pensaste que est\u00e1 mal escrito, que hay cosas que le cambiar\u00edas y despu\u00e9s te das cuenta que fuiste tu quien lo escribi\u00f3.<\/p>\n

Si estas usando alg\u00fan m\u00f3dulo, te dar\u00e1s cuenta de lo importante que es la documentaci\u00f3n, buscar\u00e1s ejemplos, querr\u00e1s saber que par\u00e1metros y que tipos de datos recibe alguna funci\u00f3n, que clase debes extender para hacer tu trabajo mas sencillo. Si el paquete\/modulo que estas pretendiendo usar no est\u00e1 bien documentado es muy probable que desistas de usarlo.<\/p>\n

Comentar vs Documentar<\/h3>\n

“Una cosa es una cosa y otra cosa es otra cosa”, antes de avanzar mas tenemos que entender la diferencia de las dos. En general comentar<\/strong> es describir tu c\u00f3digo, la audiencia esperada son otros desarrolladores encargados de mantener tu c\u00f3digo. Los comentarios ayudan al lector a entender que hace el c\u00f3digo.<\/p>\n

El codigo te dice como; los comentarios te dicen por que.<\/p>\n

– Jeff Atwood (Coding Horror)<\/p><\/blockquote>\n

Documentar<\/strong> es describir el uso y la funcionalidad \u00a0a los usuarios finales, desarrolladores tal vez, pero no son los encargados de mantener el c\u00f3digo, no necesitan ver el c\u00f3digo, necesitan usarlo.<\/p>\n

Para comentar el c\u00f3digo en Python usaremos el s\u00edmbolo de “gato” o “n\u00famero”<\/p>\n

def hello_world():\n    # Un comentario precediendo a una llamada a print\n    print(\"Hello world\")<\/pre>\n
De acuerdo al PEP8 los comentarios deben tener m\u00e1ximo 72 caracteres. Pero si por alguna raz\u00f3n lo que tratas de explicar es demasiado largo entonces puedes usar m\u00faltiples lineas.<\/p>\n
def hello_world():\n    # Esta es un comentario demasiado largo como para que \n    # entre en una sola linea, por eso lo ponemos en 2\n    print(\"Hello world\")<\/pre>\n
Comentar el c\u00f3digo tiene m\u00faltiples prop\u00f3sitos:<\/p>\n