Comentarios y Docstrings

Los comentarios están compuestos de una o mas líneas de texto que el intérprete ignora, y se usan, generalmente, para incluir comentarios relacionados con el código o para documentarlo.

Para escribir comentarios de una sola línea se usa el símbolo # (almohadilla o en inglés hashkey).

La sintaxis es:

# comentario

Este comentario puede estar aislado del código como en el siguiente ejemplo:

# Se suman dos mas dos
total = 2 + 2

O al final de una línea de código como en este otro:

total = 2 + 2 # total es igual a dos mas dos

Se pueden escribir comentarios de varias líneas con la almohadilla, siempre que se incluya al principio como en el siguiente ejemplo:

# Función sumar( param1, param2 )
# param1: es el primer parámetro
# param2: es el segundo parámetro

Hay un caso especial para la almohadilla si esta se encuentra en la primera o segunda línea del código y contiene una expresión regular detrás, ya que entonces el intérprete la procesa como una declaración de codificación.

El formato para cambiar la codificación de caracteres es el siguiente:

# -*- coding: <encoding-name> -*-

Python 3 lee los caracteres en formato UFT-8 que es un formato de codificación de caracteres que se ha convertido en un estándar universal usado cada vez más en el correo, las páginas web, bases de datos, etc.

Por ejemplo, para forzar el uso de UTF-8, se escribiría lo siguiente:

# -*- coding: utf-8 -*-

Otro caso especial es cuando la almohadilla se encuentra en la primera línea, y es seguida por un símbolo de admiración, seguida de la ruta del intérprete. A esto se le llama shebang y se usa en sistemas Linux para indicar a los scripts interpretados la ruta donde se encuentra el intérprete, el cual procesará el código.

En Linux se suele usar env seguido del nombre del intérprete así:

#!/usr/bin/env python3

Siguiendo con los comentarios, cuando hay que incluir mas de una línea se escribe el comentario, rodeado de tres comillas simples o dobles ”’ comentario ”’ o “”” comentario “””. Por ejemplo:

''' Esto es un comentario de
varias líneas.
Usando comillas simples '''

Python usa este último tipo de comentario para generar la ayuda online o docstrings, gracias al módulo pydoc que genera documentación automática para los módulos Python. Con este código escrito en el intérprete de comandos de Python se puede observar un ejemplo, en el cual se crea una clase llamada Operaciones y se le añade un comentario entre comillas dobles el cual servirá de ayuda de la clase y podremos ver si escribimos help(Operaciones).

>>> class Operaciones:
...     """
...     Esta clase se llama Operaciones
...     El método suma, suma dos números
...     El modo de uso es:
...     objeto = Operaciones()
...     objeto.suma( dato1 , dato2 )
...     """
...     def suma(self , dato1 , dato2):
...             """
...             Los parámetros de suma son: dato1 y dato2
...             """
...             return dato1 + dato2
... 
>>> help(Operaciones)

Help on class Operaciones in module __main__:

class Operaciones(builtins.object)
 |  Esta clase se llama Operaciones
 |  El método suma, suma dos números
 |  El modo de uso es:
 |  objeto = Operaciones()
 |  objeto.suma( dato1 , dato2 )
 |  
 |  Methods defined here:
 |  
 |  suma(self, dato1, dato2)
 |      Los parámetros de suma son: dato1 y dato2
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

Gracias a esto, se puede leer la ayuda, y se puede entender, que la clase se llama Operaciones, que contiene una función o método que suma dos valores y que su forma de uso sería instanciando la clase y llamando al método suma de la instancia pasándole dos argumentos, que serán los números a sumar. Lo cual nos ayuda a entender cómo usar la clase.

>>> objeto = Operaciones()
>>> objeto.suma( 2 , 2 )
4
>>> objeto.suma( 2.4 , 35.2 )
37.6