Comentarios claros en Kotlin.

Recientemente me di a la tarea de documentar el código de una aplicación que estoy desarrollando y seamos sinceros, documentar código es aburrido, tal vez por esto no pude encontrar muy buena información, en particular en la parte de cómo comentarlo. Incluso en la página oficial de Kotlin no vienen ejemplo claros de cómo comentar el código. Después de un buen rato de prueba y error descubrí algunas cosas que creo que vale la pena compartir.

Vamos a verlo con el ejemplo de un método que obtenga el subtotal de una lista del supermercado donde cada elemento tiene un precio, una cantidad y un posible descuento. Además al final le vamos a agregar un impuesto 😭 al ticket. El método podría ser el siguiente.

private fun getTicketTotal(productList: MutableList<Product>, 
taxPercentage: Double): Double {
    var total = 0.0
    for (product in productList) {
        val subtotal = (product.quantity * product.price)
        total += subtotal * ((100 - discount)/100)
    }

    val taxAmount = (total * taxPercentage)/100
    total -= taxAmount

    return total
}

Empecemos por lo más básico, un simple comentario en Kotlin se inserta con dos lineas diagonales // así:

private fun getTicketTotal(productList: MutableList<Product>, 
taxPercentage: Double): Double {
    // Creamos total en 0
    var total = 0.0
    for (product in productList) {
        // Subtotal es el la multiplicación de cantidad por precio
        val subtotal = (product.quantity * product.price)
        total += subtotal * ((100 - discount)/100)
    }

    // Sumamos el impuesto al total
    val taxAmount = (total * taxPercentage)/100
    total -= taxAmount

    return total
}

Para comentarios más largos que ocupen varios renglones podemos insertarlos con
/* ... */, aunque también podríamos tener simplemente varios renglones con //:

private fun getTicketTotal(productList: MutableList<Product>, 
taxPercentage: Double): Double {
    // Creamos total en 0
    var total = 0.0
    for (product in productList) {
        // Subtotal es el la multiplicación de cantidad por precio
        val subtotal = (product.quantity * product.price)
        /* Restamos el posible descuento al subtotal, por ejemplo si 
           el subtotal es de $150 el descuento es de 30%, el total 
           será de 150 * ((100 - 30)/100) = 150 * 0.7 = 105 */
        total += subtotal * ((100 - discount)/100)
    }

    // Obtenemos el monto de impuestos, por ejemplo si el total es 
    // 150 y el impuesto es 15%: 
    // taxAmount = (150 * 15)/100 = 22.5
    val taxAmount = (total * taxPercentage)/100
    total -= taxAmount

    return total
}

Finalmente, para comentar un método completo podemos utilizar /** ... */, aquí podemos indicar también cuales son los parámetros que necesita el método y qué es lo que regresa, así:

/**
* Este método obtiene el total de una lista de [Productos] teniendo
* en cuenta [Producto.precio], [Producto.cantidad], 
* [Producto.descuento] y un posible impuesto.
*
* @param productList La lista de productos de la cual se obtiene el * total
* @param taxPercentage El porcentaje, el cual puede ir de 0 a 100
*
* @return El total después de impuestos.
**/
private fun getTicketTotal(productList: MutableList<Product>, 
taxPercentage: Double): Double {
    // Creamos total en 0
    var total = 0.0
    for (product in productList) {
        // Subtotal es el la multiplicación de cantidad por precio
        val subtotal = (product.quantity * product.price)
        /* Restamos el posible descuento al subtotal, por ejemplo si 
           el subtotal es de $150 el descuento es de 30%, el total 
           será de 150 * ((100 - 30)/100) = 150 * 0.7 = 105 */
        total += subtotal * ((100 - discount)/100)
    }

    // Obtenemos el monto de impuestos, por ejemplo si el total es 
    // 150 y el impuesto es 15%: 
    // taxAmount = (150 * 15)/100 = 22.5
    val taxAmount = (total * taxPercentage)/100
    total -= taxAmount

    return total
}

Como puedes observar hay palabras que encerré entre [] esto es para que puedas dar option + clic en esa clase o incluso en un método o campo dentro de la clase y te lleve directamente a ella. Ahora es mucho más claro lo que hace el método, sí es aburrido, pero tus compañeros (y tu yo del futuro) te lo agradecerán.

NOTA: No todos los métodos e instrucciones necesitan comentarios, hay unos que son auto explicativos.

Si te gustó el artículo compártelo suscríbete y sígueme en mis redes sociales o donde quieras. También te invito a dejar tus comentarios. ¡Saludos y mucho éxito!

Publicado por Jesus Almaral

Soy ingeniero en Mecatrónica con maestría en Machine Learning, tengo experiencia en lenguajes como Java, Kotlin, Matlab, Android, Python, etc. Actualmente soy desarrollador de aplicaciones móviles, me gusta la música y toco la guitarra, me gusta mucho saber cosas sobre el universo, leer y comer tacos. También me apasiona enseñar.

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios .

A %d blogueros les gusta esto: