Comentarios en Swift

Poner comentarios o no poner comentarios. Ésa es la cuestión.

En cualquier lenguaje de programación se permite la introducción de comentarios en el código. Ciertamente, podemos escribir comentarios, ¿pero hoy en día tiene sentido poner mensajes en el código?

Te respondo. Haz lo que consideres adecuado. En general, estarás trabajando en equipo, habrán acuerdos de equipo, y el equipo habrá decidido qué es lo correcto. Sin embargo, en este artículo, voy a proponer varias ideas para evitar la introducción de comentarios innecesarios.

¿Cómo se introducen comentarios en Swift?

Tenemos dos formas.

• La primera sería para introducir un comentario de una sola linea.

// Esto es una forma de introducir un comentario

• La segunda sería para introducir más de una linea comentada.

/*
Si queremos comentar más de una linea para explicar más
y no alargar una linea 
*/

La longitud de un nombre de una variable debería ser proporcional a su alcance. La longitud de un nombre de una función o de una clase es la inversa.

En los lenguajes de programación antiguos, los nombres de las variables, funciones o clases estaban limitados con lo cual, teníamos que ir con cuidado y ser muy específicos. Pero, hoy en día, no tenemos dicha limitación. Por lo tanto, usémoslo.

• Si vamos a crear una variable global, intentaremos ser lo más específicos posibles, es decir, su nombre será lo suficientemente largo que explique lo que representa.

Un mal ejemplo sería el siguiente.

// columns in table view ....
let columns: Int = 2

Como recomendación, podríamos aprovechar el código del comentario y añadirlo a la variable.

let columnsInTableView: Int = 2

Condiciones casi infinitas

No se recomienda usar condiciones complejas o condiciones largas. Podemos pensar que el hecho de que sea una condición así hace que una posible solución sea, poner un comentario.

// If both users are near and they have the same score
if process(a, b) < .near && calculate(a) == calculate(b) {
    doSometing()
}

Una posible solución sería crear una función de esta forma.

if bothUsersAreNearAndHaveSameScore() {
    doSomething()
}
func bothUsersAreNearAndHaveSameScore() -> Bool {
    process(a, b) < .near && calculate(a) == calculate(b)
}

Entonces, ¿dónde podemos crear comentarios?

• Si nuestro código es una librería que va a ser usado por un equipo externo al nuestro, te recomiendo que crees comentarios a modo de documentación para luego generarla.

/// This function calculate something  
///    
/// - Parameters:    
///   - name:    The name of the function.    
///   - request: The request.
func calculateSomething(name: String, request: [String: Any])

Pero ojo, que si no ofrece más información de la que ya podemos tener en nuestra función, ¿para qué?

• En Swift podemos poner marcas en el código.

// MARK: - Life Cycle

¿Otros sitios?

Hay gente que le gusta poner ToDo. En general, un ToDo es algo que nunca lo harás, así que, en general, intenta no engañarte. Hoy en día, usamos más herramientas de documentación, aprovecha para poner esos ToDos en el backlog.

Comentar el código es una muy mala práctica. Para pruebas personales y trabajos en curso es normal tener código comentado, pero cuando terminas el trabajo, intenta no dejar código comentado.

Y, para terminar, un consejo, si tu código necesita un comentario, considera por qué necesita un comentario y piensa en como solucionar el código para que no sea necesario dicho comentario.