Respuesta.

Los paquetes, importaciones y declaraciones a nivel de archivo son la base de la estructura de cualquier proyecto en Kotlin, y los desarrolladores a menudo se enfrentan a preguntas sobre la organización del espacio de nombres y la visibilidad de las funciones.

Historia del tema: Kotlin, continuando con las tradiciones de Java, soporta un sistema de paquetes, pero agrega el concepto de declaraciones a nivel de archivo, lo que permite crear funciones y propiedades fuera de una clase, mejorando la modularidad y expresividad del código.

Problema: ¿Cómo organizar la visibilidad y el punto de entrada a funciones, propiedades y clases de la manera más conveniente, evitando conflictos de nombres, importaciones dobles y dependencias excesivas entre partes del proyecto?

Solución:

Para cualquier archivo, se puede declarar explícitamente un package (coinciden con la estructura del archivo, pero pueden no coincidir estrictamente)
En un mismo archivo se pueden colocar varias clases, funciones y propiedades a nivel superior, así como declaraciones de objeto
Se pueden importar tanto miembros individuales como grupos utilizando * o alias

Ejemplo de código:

package utils

import kotlin.math.*
import model.User as UserModel

fun sum(a: Int, b: Int) = a + b

val PI2 = PI * 2

Características clave:

Objetos y funciones a nivel superior están disponibles por package, no requieren la creación de instancias de clase
Los importes pueden tener alias, lo que ayuda a evitar conflictos de nombres
Se pueden importar funciones, propiedades y objetos de tipo object

Preguntas engañosas.

¿Pueden diferentes archivos con el mismo nombre de paquete contener declaraciones con los mismos nombres de funciones/propiedades?

Sí, pero esto llevará a un conflicto de nombres durante la compilación si no se utilizan diferentes nombres o alias para las importaciones. Las declaraciones a nivel de archivo funcionan dentro del paquete.

¿Es necesario que la estructura de carpetas del proyecto repita el paquete, como en Java?

No, esto es solo recomendable para la organización del código y la facilidad de mantenimiento, pero el compilador permite diferencias entre rutas y paquetes. Sin embargo, al trasladar el código o construir con herramientas, pueden surgir dificultades con el registro y la modularidad.

¿Se pueden declarar múltiples paquetes dentro de un solo archivo .kt?

No, en un solo archivo .kt solo se puede declarar un paquete. Mezclar paquetes lleva a un error de compilación.

Errores comunes y anti-patrones

No cumplir con un acuerdo único sobre nomenclatura y estructura de paquete/carpeta
Poner demasiadas temáticas diferentes en un solo archivo, mezclando lógica de negocio y funciones utilitarias
Usar importaciones * en todos los archivos en lugar de importaciones según sea necesario — disminuye la legibilidad, puede llevar a conflictos

Ejemplo de la vida real

Caso negativo

Todas las funciones auxiliares de diferentes temáticas están ubicadas en un solo paquete utils, el archivo Utility.kt contiene varios métodos comerciales y técnicos:

Ventajas:

Fácil de encontrar todas las utilidades en un solo lugar

Desventajas:

El archivo crece mucho, se pierde el contexto de las funciones, es más difícil de mantener, la refactorización se complica

Caso positivo

Se adhieren estrictamente a los acuerdos: cada paquete refleja el dominio, se utiliza a nivel de archivo solo para funciones que no pertenecen a ninguna clase, se utilizan alias para eliminar duplicaciones, cada archivo para su temática: