feat: add cargo modules

Author: SergioRibera

content/4.cargo/2.modules.md

@@ -0,0 +1,257 @@
+---
+title: 'Cargo'
+description: ''
+draft: true
+data:
+  type: 'custom'
+  topicLevel: 'start'
+  position:
+    x: 200
+    y: 750
+  sourcePosition:
+    error-handling: 'right'
+  targetPosition:
+    traits: 'bottom'
+---
+# Organizando Proyectos en Rust: Módulos y Visibilidad
+
+Cuando desarrollamos en Rust, mantener el código organizado es esencial para la escalabilidad y la mantenibilidad. Rust ofrece un sistema de módulos flexible que nos ayuda a dividir el código en componentes más manejables. En este artículo exploraremos cómo crear y gestionar módulos, controlar su visibilidad, y estructurar proyectos de manera eficiente, abordando las prácticas más recomendadas en la comunidad.
+
+---
+
+## Introducción a los módulos
+
+Los módulos en Rust agrupan código relacionado bajo un espacio de nombres, permitiendo:
+
+- **Organización lógica:** Divide el código en archivos o directorios.
+- **Encapsulación:** Restringe qué partes del código son accesibles externamente.
+- **Reutilización:** Facilita la modularidad y el uso compartido de código.
+
+Un módulo puede contener funciones, estructuras, enumeraciones, constantes e incluso otros módulos.
+
+---
+
+## Crear y gestionar módulos
+
+### Módulos en el mismo archivo
+La forma más sencilla de declarar un módulo es hacerlo directamente en el archivo:
+
+```rust
+mod math {
+    pub fn add(a: i32, b: i32) -> i32 {
+        a + b
+    }
+}
+```
+
+Luego accedes a los elementos públicos con el prefijo del módulo:
+```rust
+fn main() {
+    let sum = math::add(2, 3);
+    println!("Suma: {}", sum);
+}
+```
+
+### Módulos en archivos separados
+Para mantener el código limpio, puedes mover los módulos a archivos independientes:
+
+En `main.rs`:
+```rust
+mod math;
+
+fn main() {
+    let sum = math::add(5, 7);
+    println!("Suma: {}", sum);
+}
+```
+
+En `math.rs`:
+```rust
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+```
+
+### Módulos como directorios
+Si un módulo incluye submódulos, puedes organizarlo en un directorio con un archivo `mod.rs` o estructurarlo usando archivos con el mismo nombre que los submódulos.
+
+Estructura de ejemplo:
+```
+src/
+├── main.rs
+├── math/
+│   ├── mod.rs
+│   ├── add.rs
+│   └── multiply.rs
+```
+
+En `math/mod.rs`:
+```rust
+pub mod add;
+pub mod multiply;
+```
+
+---
+
+## Control de visibilidad
+
+Por defecto, los módulos y sus elementos son privados. Para hacerlos accesibles, usa `pub`.
+
+```rust
+mod shapes {
+    pub struct Rectangle {
+        pub width: u32,
+        pub height: u32,
+    }
+
+    impl Rectangle {
+        pub fn area(&self) -> u32 {
+            self.width * self.height
+        }
+    }
+}
+```
+
+El acceso desde otro módulo o función será así:
+```rust
+fn main() {
+    let rect = shapes::Rectangle { width: 10, height: 20 };
+    println!("Área: {}", rect.area());
+}
+```
+
+---
+
+## Estructuración recomendada para proyectos Rust
+
+La organización de un proyecto depende de su propósito. Aquí hay patrones comunes:
+
+### 1. **Proyectos ejecutables simples**
+Los proyectos pequeños suelen tener un único archivo `main.rs`:
+
+```
+src/
+└── main.rs
+```
+
+### 2. **Proyectos ejecutables grandes**
+A medida que crece, puedes mover lógica a módulos:
+
+```
+src/
+├── main.rs
+├── config.rs
+├── handlers.rs
+└── utils.rs
+```
+
+En `main.rs`:
+```rust
+mod config;
+mod handlers;
+mod utils;
+```
+
+### 3. **Bibliotecas**
+Las bibliotecas usan un archivo `lib.rs` para exponer su API pública:
+
+```
+src/
+├── lib.rs
+└── utils.rs
+```
+
+En `lib.rs`:
+```rust
+pub mod utils;
+```
+
+### 4. **Híbridos (ejecutable + biblioteca)**
+Un proyecto puede tener `main.rs` para la aplicación y `lib.rs` para lógica reutilizable:
+
+```
+src/
+├── lib.rs
+└── main.rs
+```
+
+En `main.rs`:
+```rust
+use mycrate::utils::some_function;
+
+fn main() {
+    some_function();
+}
+```
+
+En `lib.rs`:
+```rust
+pub mod utils {
+    pub fn some_function() {
+        println!("Función compartida");
+    }
+}
+```
+
+### 5. **Proyectos con múltiples binarios**
+Usa un directorio `src/bin/` para incluir otros ejecutables:
+
+```
+src/
+├── main.rs
+├── lib.rs
+└── bin/
+    ├── tool1.rs
+    └── tool2.rs
+```
+
+---
+
+## Puntos de entrada: `main.rs` y `lib.rs`
+
+### `main.rs`
+Es el punto de entrada de los ejecutables. Aquí defines la lógica inicial de tu programa.
+
+### `lib.rs`
+Sirve como punto de entrada para bibliotecas. Aquí defines qué módulos y funciones serán públicos para los usuarios de la biblioteca.
+
+### Coexistencia de `main.rs` y `lib.rs`
+En proyectos híbridos, `lib.rs` puede contener la lógica principal reutilizable y `main.rs` consumirla:
+
+En `lib.rs`:
+```rust
+pub fn greet(name: &str) {
+    println!("Hola, {}!", name);
+}
+```
+
+En `main.rs`:
+```rust
+use mycrate::greet;
+
+fn main() {
+    greet("Mundo");
+}
+```
+
+---
+
+## Buenas prácticas y convenciones
+
+1. **Divide y vencerás:** Usa módulos para separar responsabilidades.
+2. **Restricción de visibilidad:** Haz públicos solo los elementos necesarios.
+3. **Nombres consistentes:** Usa nombres descriptivos para módulos y archivos.
+4. **Centraliza lo común:** Mueve funciones reutilizables a `lib.rs`.
+
+---
+
+## Configuraciones adicionales para módulos
+
+- **Agrupación lógica:** Usa directorios para módulos con múltiples submódulos.
+- **Macros compartidas:** Crea un módulo separado para macros reutilizables, por ejemplo, `src/macros.rs`.
+
+---
+
+## Conclusión
+
+Organizar proyectos con módulos en Rust no solo mejora la claridad del código, sino que también facilita su escalabilidad. Ya sea que trabajes en un ejecutable, una biblioteca o ambos, seguir estas prácticas te ayudará a mantener un código limpio, reutilizable y fácil de entender. ¡Experimenta con estas técnicas y lleva tus proyectos al siguiente nivel! 🚀