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!
Hackaprende 