Funciones de nivel superior y ficheros

Kotlin te deja escribir una función sin clase que la contenga. Es una de esas libertades que se disfrutan sin pensar hasta que alguien llama a tu código desde Java y descubre una clase llamada UtilidadesKt que tú nunca escribiste. Esa clase existe, tiene un nombre concreto, depende del nombre de tu fichero y forma parte de tu API pública en la JVM. Aprender a controlarla es la diferencia entre una biblioteca que se organiza sola y una que se rompe cuando alguien renombra un archivo.

El fichero no es la clase

En Java el fichero y la clase pública están atados: mismo nombre, misma unidad, un tipo por archivo. En Kotlin esa atadura no existe. Un fichero puede contener cero, una o veinte declaraciones de nivel superior, de cualquier clase, y su nombre no tiene que coincidir con ninguna.

// fichero: texto/Normalizacion.kt
package com.ejemplo.texto

private val ESPACIOS = Regex("\\s+")

fun normalizar(s: String): String = s.trim().replace(ESPACIOS, " ")

fun String.sinAcentos(): String = /* ... */ this

internal fun claveDeBusqueda(s: String) = normalizar(s).lowercase()

El espacio de nombres real es el paquete, no una clase artificial. Eso elimina de un plumazo la familia de clases con constructor privado y métodos estáticos que Java obliga a inventar, y hace que la importación sea granular: se importa una función concreta, y con as se le pone un alias local si choca con otra.

A diferencia de lo que ocurría con las funciones locales, aquí el orden de declaración es irrelevante: dentro de un fichero, cualquier declaración de nivel superior ve a todas las demás, estén arriba o abajo. Y las visibilidades cambian de significado: private confina la declaración a su fichero, e internal la abre a todo el módulo pero la cierra al resto del mundo.

La clase que no escribiste

La JVM no admite métodos fuera de una clase, así que el compilador fabrica una fachada. La regla es mecánica: se toma el nombre del fichero, se quita la extensión, se pone la inicial en mayúscula y se añade el sufijo. Un fichero Normalizacion.kt produce la clase NormalizacionKt, con todas las funciones de nivel superior como métodos estáticos públicos y las propiedades de nivel superior como campos estáticos con sus accesores.

// Lo que ve Java del fichero anterior:
String limpio = NormalizacionKt.normalizar("  hola   mundo ");
String plano  = NormalizacionKt.sinAcentos("canción");

Fíjate en el segundo caso: una función de extensión no es un método del tipo receptor, es un método estático cuyo primer parámetro es el receptor. Desde Kotlin se lee como si perteneciera a String; desde Java se ve la verdad.

De aquí sale una trampa que muerde a las bibliotecas. El nombre del fichero es parte de tu API binaria en la JVM. Renombrar Normalizacion.kt a Texto.kt no cambia una sola línea de código Kotlin ni rompe a ningún consumidor Kotlin, pero cambia la clase de NormalizacionKt a TextoKt y todo binario Java compilado contra la versión anterior falla al enlazar. Es una refactorización aparentemente cosmética con consecuencias de versión mayor.

flowchart TD
F[Fichero Normalizacion punto kt] --> C[Clase NormalizacionKt]
C --> M1[normalizar como metodo estatico]
C --> M2[sinAcentos con el receptor como primer parametro]
C --> P[Propiedades como campos estaticos]
R[Renombrar el fichero] --> N[Cambia el nombre de la clase]
N --> B[Rompe a los consumidores Java ya compilados]
style B fill:#f38ba8,color:#11111b
style C fill:#89b4fa,color:#11111b

@JvmName y la fachada multifichero

La solución es dejar de depender del nombre del archivo y fijarlo explícitamente. La anotación va al principio del fichero, con el prefijo de destino de fichero, y antes de la declaración package.

@file:JvmName("Textos")

package com.ejemplo.texto

fun normalizar(s: String): String = /* ... */ s

Ahora Java escribe Textos.normalizar(...) y tú puedes renombrar el .kt cuantas veces quieras. Para una biblioteca con consumidores Java, esta anotación no es un adorno: es lo que convierte el nombre de un archivo en un detalle interno.

El siguiente problema aparece al crecer. Quieres partir un fichero de dos mil líneas en cinco, pero que Java siga viendo una sola clase de utilidades. Poner el mismo @JvmName en los cinco es un error de compilación por nombre duplicado, salvo que añadas también la anotación de clase multifichero:

// Cadenas.kt
@file:JvmName("Textos")
@file:JvmMultifileClass
package com.ejemplo.texto

fun normalizar(s: String) = s.trim()

// Comparacion.kt
@file:JvmName("Textos")
@file:JvmMultifileClass
package com.ejemplo.texto

fun similares(a: String, b: String) = normalizar(a) == normalizar(b)

El compilador genera entonces una clase fachada Textos que reexpone todo, más una clase parte por cada fichero con nombres derivados que no debes tocar. Para Kotlin no cambia nada; para Java aparece una única puerta de entrada. Es exactamente el mecanismo con el que la propia stdlib presenta cientos de extensiones repartidas en decenas de ficheros bajo nombres como StringsKt o CollectionsKt.

Organizar una API sin clases envoltorio

Con estas piezas, el diseño de una biblioteca Kotlin deja de girar en torno a clases contenedoras. Cuatro criterios que se sostienen bien.

Agrupa por concepto y no por naturaleza técnica. Un paquete pedidos con sus tipos, sus extensiones y sus funciones libres se lee mucho mejor que un paquete utils con todo lo que no cabía en otro sitio. El nombre utils es casi siempre la confesión de que no se encontró el concepto.

Prefiere la extensión a la función suelta cuando haya un receptor natural. fun String.sinAcentos() aparece al escribir un punto tras cualquier cadena; fun sinAcentos(s: String) solo lo encuentra quien ya sabe que existe. El descubrimiento en el IDE es una propiedad de diseño, no un accidente.

Marca la frontera con visibilidades explícitas. Todo lo que no sea contrato debería ser internal o private. En una biblioteca, activar el modo de API explícita obliga además a anotar visibilidad y tipo de retorno de cada declaración pública, y convierte esa disciplina en un error de compilación en lugar de una intención.

Y fija los nombres JVM desde el primer día si esperas consumidores Java. Poner @file:JvmName cuando el fichero se crea cuesta una línea; ponerlo después de publicar significa mantener las dos clases durante un ciclo de deprecación.