Líneas de comentario
| Sigla | CLOC (CLOC(rec) en la variante recursiva de paquete) |
| Aspecto | «Documentación» |
| Se mide en | método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero |
| Tipo de valor | recuento (entero, mínimo 0) |
| Dirección | informativa: ni alto ni bajo es mejor |
| Origen | no hay una definición original única; es un recuento elemental que casi toda herramienta ofrece |
| Stau Metro | CommentLinesOfCodeMethod, CommentLinesOfCodeClass, CommentLinesOfCodeInterface, CommentLinesOfCodePackage, CommentLinesOfCodeRecursivePackage, CommentLinesOfCodeModule, CommentLinesOfCodeProject, CommentLinesOfCodeFileType |
En pocas palabras
Cuenta cuántas líneas de un método, una clase o un paquete están ocupadas por comentarios. Si un comentario de bloque ocupa cinco líneas, suma cinco; si una línea tiene código y un comentario al final, también suma una. Es el ingrediente básico de las métricas de documentación: por sí sola dice cuánto texto de comentario hay, no si es útil.
Qué mide
El volumen de texto de comentario de un elemento. No mide la calidad de los comentarios, ni si explican el porqué o repiten lo que ya dice el código, ni si están al día. Un comentario de licencia de veinte líneas pesa lo mismo que veinte líneas de explicación.
Por eso se usa casi siempre dividida por el tamaño del elemento (véase el «ratio de comentarios»), o para detectar casos extremos: elementos sin un solo comentario o elementos casi enteros de comentario (a menudo, código antiguo comentado).
Cómo se calcula
Para cada comentario se cuentan las líneas físicas del texto fuente que tienen algún carácter distinto de espacio o tabulador. El valor de un elemento es la suma sobre sus comentarios.
Reglas que conviene tener presentes:
- Una línea de un comentario de bloque que esté en blanco no cuenta; una que solo tenga
*sí. - Una línea con código y un comentario al final cuenta como línea de comentario, y además sigue siendo una línea de código. Las dos cifras se solapan.
- Como se suma por comentario, una línea con dos comentarios (
/* a */ /* b */) cuenta dos veces. - Los comentarios de documentación (
/** … */) cuentan como cualquier otro comentario; para aislarlos existe «JLOC».
Ejemplo
class Pricing {
/**
* Applies the discount.
*
* @param price the base price
* @return the final price
*/
double apply(double price) {
// no discount below 100
if (price < 100) {
return price; // unchanged
}
return price * 0.9;
}
}
En apply: el Javadoc ocupa 6 líneas (/**, tres de texto, la línea * vacía y */), más // no discount below 100 (1) y // unchanged (1). CLOC del método = 6 + 1 + 1 = 8. Como la clase Pricing no tiene otros
comentarios, su CLOC también es 8.
Cómo interpretarla
No tiene valor bueno ni malo, y por eso no tiene umbrales. Se lee comparándola:
- con el tamaño del elemento: el «ratio de comentarios» lo hace por ti;
- con las «líneas de Javadoc»: la diferencia son los comentarios ordinarios;
- entre elementos del mismo nivel: un valor 0 en un método largo o en una clase pública merece una mirada; un valor enorme en un fichero pequeño suele ser una cabecera de licencia o código comentado.
Ojo. Más comentarios no significan mejor documentación. Un valor alto puede indicar código que necesita muchas explicaciones, o código muerto comentado.
Relación con otras métricas
- «Ratio de comentarios» (
COM_RAT):CLOCdividida por las líneas del elemento. - «Ratio real de comentarios» (
TCOM_RAT): cuenta solo las líneas que son exclusivamente comentario. - «Líneas de Javadoc» (
JLOC): la parte deCLOCque son comentarios/** */. - «Líneas de código» (
LOC): el tamaño con el que se compara. - «Líneas de código sin comentarios» (
NCLOC): las líneas que no son solo comentario.
En las herramientas
Stau Metro. El valor depende del nivel:
- Método (
CommentLinesOfCodeMethod): todos los comentarios dentro del texto del método, incluido su Javadoc y los de lambdas y clases anónimas o locales que contenga. - Clase (
CommentLinesOfCodeClass) e interfaz (CommentLinesOfCodeInterface): los comentarios de la clase, incluidos los de sus métodos y los de las clases anónimas o locales que declare, pero no los de sus clases o interfaces anidadas con nombre, que tienen su propio valor. Los comentarios fuera de toda clase (la cabecera de licencia, por ejemplo) no se atribuyen a ninguna. Los enumerados y los records tienen valor de clase; los tipos de anotación (@interface) no tienen valor ni de clase ni de interfaz. - Paquete (
CommentLinesOfCodePackage), módulo (CommentLinesOfCodeModule) y proyecto (CommentLinesOfCodeProject): todos los comentarios de todos los ficheros, de cualquier lenguaje, también los de XML, y los de cabecera. La variante recursiva (CommentLinesOfCodeRecursivePackage) suma además los de los subpaquetes: cada paquete recibe lo suyo y lo de sus descendientes. - Tipo de fichero (
CommentLinesOfCodeFileType): lo mismo, agrupado por el tipo de fichero.
Se recorren los ficheros del ámbito analizado, también los de test. Por eso el valor de un paquete puede ser mayor que la suma de los de sus clases.
SonarQube (comment_lines): «el número de líneas que contienen comentario o código comentado». No cuenta los
comentarios no significativos (líneas de comentario vacías o solo con caracteres especiales) ni las cabeceras de
fichero de Java, que suelen ser la licencia. Stau Metro cuenta ambas cosas.
Referencias
- SonarQube, definición de métricas: https://docs.sonarsource.com/sonarqube-server/latest/user-guide/code-metrics/metrics-definition/