DEV Community: José María CL

Cómo comunicarte mejor con tu IA de cabecera

José María CL — Sun, 23 Mar 2025 20:47:23 +0000

Disclaimer: Esto no es un post enteramente escrito por mi. Es un texto condensado a partir de las respuestas que me dio Cursor AI mientras conversabamos.

Intro

Hola. Hace unos días decidí experimentar trabajando con Cursor AI y dejando que hiciera la mayor cantidad del trabajo posible sin que yo interviniera más que para dar instrucciones. Muy pronto descubrí 4 cosas:

El reto de pensar los pasos y soluciones no te lo ahorras, más bien ese se vuelve tu principal responsabilidad.
La IA hace muy bien el trabajo duro de escritura de código, y es capaz de tomar decisiones bien enfocadas y delimitadas.
No solo se trata de dar instrucciones, también hay que escuchar
Nos volvemos un equipo de 2, así que el eje principal es la comunicación. Entre mejor comunicación y claridad tengamos el uno con el otro, ambos somos más conscientes de lo que está pasando.

🤔 ¿Hay a estas alturas una metodología o técnica que nos permita trabajar lo mejor posible con nuestro aliado virtual? La verda, lo desconozco. No he leído artículos "serios" pero sí que he recibido consejos de colegas que ya han estado trabajando de esta manera desde hace algún tiempo. Además, le he pedido al mismo Cursor AI que me diera recomendaciones para hacerme entender mejor. Esto es lo que me ha dicho:

🤖 Cursor AI: Para ayudarme a entender mejor tus requerimientos
y ser más efectivo, te sugiero seguir estas pautas:

Estructura recomendada para las Instrucciones:

Objetivo: [Descripción clara del objetivo]
Contexto: [Información relevante del sistema/componente]
Requisitos: [Lista de requisitos específicos]
Restricciones: [Limitaciones o consideraciones especiales]

Como yo le solicito las cosas al empezar a trabajar en la feature:

Hola. Vamos a crear un endpoint nuevo en el proyecto. 

El objetivo es implementar un nuevo endpoint que cubra el caso de uso de actualización parcial del usuario.

Antes de empezar, analiza el módul "auth" en el que implementé la creación de usuarios. Pon atención al estilo y patrón: 

el controlador de express está en infrastructure/routes. Este se encarga preparar los colaboradores para pasarlos al servicio de aplicación. En application se realiza la de verificación de existencia del usuario, verificación del payload, persistencia de datos a través del userRepository, respuesta del resultado y gestión de errores

Los requisitos son:
- Crear endpoint patch /users/:id
- Actualización parcial del usuario y su perfil
- Mantener los datos existentes no incluidos en el payload
- Validar datos


Restricciones:
- Realizar los nuevos cambios en el módulo de users
- Gestionar errores usando custom exceptions. Agregar nuevas si es necesario o reutilizar las existentes si es apropiado
- No intentes corregir errores de eslint
- Usa el mismo estilo que se ha usado para el signup y signin

Orden de los cambios:
Primero realiza los cambios nucleares en el repository y finalmente la ruta de express

A partir de ahí voy haciendo las correcciones, ajustes y siguientes pasos con instrucciones más pequeñas.

Ejemplo de una Solicitud Bien Estructurada según Cursor AI (un poco excesivo para mi gusto, pero funciona):

Objetivo: Implementar endpoint PATCH para actualización parcial de usuarios

Contexto:
- Módulo de users
- Seguir patrones existentes del módulo de auth
- Implementar actualización parcial (PATCH)
- Mantener consistencia con la arquitectura actual

Requisitos:
1. Endpoint PATCH /users/:id
2. Actualización parcial de datos del usuario y su perfil
3. Solo el ID es requerido en el payload
4. Mantener datos existentes no incluidos en el payload
5. Implementar validación de datos
6. Seguir el patrón de manejo de errores existente

Estructura de Datos:
Payload esperado (todos los campos son opcionales excepto id):
{
  "id": string,
  "fullName": string,
  "email": string,
  "phone": string,
  "status": "active" | "inactive" | "banned",
  "onlineStatus": "online" | "offline" | "away"
}

Componentes a Modificar/Crear:
1. Interface UserRepository:
   - Añadir método update(user: User): Promise<User>

2. PrismaUserRepository:
   - Implementar método update
   - Manejar actualización parcial de datos
   - Mantener datos existentes

3. Routes:
   - Crear endpoint PATCH
   - Implementar validación de datos
   - Manejar errores

4. Validators:
   - Crear schema de validación para actualización parcial

Restricciones:
- Mantener la estructura de dominios actual
- Seguir el patrón de manejo de errores existente
- Validar datos según reglas de negocio
- Mantener la consistencia de datos

Consideraciones Técnicas:
- Usar el mismo patrón de manejo de errores que auth
- Mantener la separación de responsabilidades
- Seguir el patrón de validación existente
- Implementar logs para debugging

¿Podrías proceder con la implementación siguiendo este orden:
1. Interface y Repository
2. Validator
3. Route
4. Tests

Esta estructura me ayuda a:

Entender claramente el alcance del cambio

Identificar los componentes que necesito modificar

Mantener la consistencia con el código existente

Seguir el patrón de arquitectura actual

Implementar la funcionalidad de manera incremental

Para Describir Cambios o Nuevas Funcionalidades:

Antes: "Quiero que hagas X"
Mejor: "Necesito implementar X porque [razón] y debe cumplir con [requisitos específicos]"

Para Reportar Problemas:

Antes: "No funciona el endpoint"
Mejor: "El endpoint /api/auth/signin devuelve error 500 cuando [condición específica]"

Para Solicitar Mejoras:

Antes: "Hazlo más rápido"
Mejor: "Necesito optimizar el rendimiento del endpoint X para manejar Y peticiones por segundo"

Para Manejar Complejidad:

Dividir las tareas grandes en subtareas
Especificar el orden de prioridad
Indicar dependencias entre componentes

Para Validar Cambios:

Proporcionar ejemplos de casos de uso
Especificar el comportamiento esperado
Indicar cómo probar los cambios

Para Contexto Técnico:

Mencionar versiones de dependencias relevantes
Indicar restricciones de infraestructura
Especificar patrones de diseño a seguir

Para Decisiones de Arquitectura:

Proporcionar contexto del sistema actual
Mencionar consideraciones de escalabilidad
Indicar restricciones de rendimiento

Para Manejo de Errores:

Describir el comportamiento actual
Especificar el comportamiento deseado
Proporcionar logs o ejemplos de error

Para Testing:

Especificar casos de prueba
Indicar cobertura esperada
Mencionar tipos de pruebas necesarias

Ideas finales

Iré actualizando esto según entienda mejor cómo trabajar de esta manera. Son nuevos tiempos. Una nueva manera de hacer las cosas, y deberíamos usar esto a nuestro favor antes de que alguien lo vuelva hacia nuestra contra.

Si tienes consejos, correcciones y observaciones, por favor compartelas :)

How are you so productive

José María CL — Sat, 25 Jan 2025 21:34:31 +0000

Cómo usar varias SSH keys para diferentes repositorios de GitHub (o GitLab)

José María CL — Mon, 04 Nov 2024 07:36:40 +0000

Introducción

Hola. Hoy veremos algunas configuraciones para trabajar con repositorios de diferentes cuentas de GitHub o GitLab.

Git y GitHub nos sugieren una configuración global y general que es útil para la gran mayoría de los usuarios:

Instalar Git
Configurar el name y el email globales para la firma de commits
Generar keys SSH personales
Configurar las keys en GitHub
Clonar el repo con SSH
Ser felices

Sin embargo, hay un caso más o menos común en el que, ya sea por el trabajo o proyectos personales, tenemos que trabajar con diferentes cuentas de GitHub o GitLab, con diferente usuario o correo en la firma, y desde la misma computadora.

Resúmen

El truco es simple. Se trata de algunos ajustes de configuración SSH y de Git:

(SSH) Generar una key SSH diferente para cada cuenta de GitHub
(SSH) Crear un archivo de configuración SSH global
(Git) Configurar el remote origin de cada repositorio
(Git) Settear el name y el email para cada repositorio

⚠️ Consideraciones

En este post usaremos el remote con SSH. Si ya clonaste el repositorio usando la opción HTTPS dirígete al final del post para cambiar la URL del remote y poder continuar con el tutorial.

Para verificar qué tipo de clonación escogiste cuando clonaste el repo, lo puedes averiguar llendo a tu repositorio en la terminal y usando el comando git remote -v:

En este ejemplo podemos ver que en la salida aparece https, lo que significa que tendríamos que cambiar la url para que sea ssh.

# Navegar al repositorio
cd ~/Documents/work/git-tricks-and-tutorials

# Mostrar el remote
git remote -v
# origin    https://github.com/ChemaCLi/git-tricks-and-tutorials.git (fetch)
# origin    https://github.com/ChemaCLi/git-tricks-and-tutorials.git (push)

Objetivo del ejercicio

Supongamos que tenemos 2 cuentas de GitHub: Una cuenta personal y una cuenta del trabajo. Lo que haremos es crear una configuración personal para la cuenta personal, y una configuración work para la cuenta de nuestro trabajo.

1. Generar y preparar las nuevas keys SSH

Lo primero que debemos hacer es navegar a la carpeta .ssh de nuestra computadora.

El directorio .ssh debe estar en la ruta raíz de tu usuario. Si no la puedes ver, asegúrate de que la opción "Ver archivos ocultos" esté habilitada en tu Sistema Operativo (MacOS, Linux o Windows).

Dentro del directorio .ssh encontrarás los archivos id_rsa y id_rsa.pub.

Si no existen, revisa la sección de Consideraciones de este post por favor.

En mi caso estas son las keys que uso para mis proyectos personales, así que crearé una carpeta personal para colocarlas allí, y crearé una carpeta work para la cuenta del trabajo

Lo siguiente será crear una nueva key SSH para el trabajo (usando el email de mi trabajo) con los siguientes comandos:

# Navega a la carpeta .ssh/work
cd ~/.ssh/work
# Genera la nueva key allí dentro
ssh-keygen -t rsa -b 4096 -C "chema@devu.community"

Al presionar Enter nos preguntará qué nombre le queremos dar al archivo. Te sugiero que le pongas el nombre de la empresa de tu trabajo para evitar confusiones. Usaré "devu" en mi caso.

Enter file in which to save the key (/Users/chema/.ssh/id_rsa): devu

Presiona Enter un par de veces para continuar sin poner una contraseña, o especifica una si lo prefieres.

Ahora tendrás tus keys ssh organizadas de esta manera:

Lo siguiente por hacer es agregar la nueva SSH key en tu cuenta de GitHub del trabajo. Si no sabes cómo hacerlo, puedes seguir las instrucciones del paso 4 de la guía que escribí en este otro post:

Cómo instalar y configurar Git y SSH con GitHub en Mac, GNU/Linux o Windows (GitBash)

José María CL ・ Jan 9 '22

#git #github #tutorial #español

2. Archivo config SSH

La clave y la magia de todo lo que estamos haciendo recae en gran parte sobre este paso, así que presta atención.

Crea un archivo de texto plano con el nombre config dentro de tu carpeta .ssh. Asegúrate de que no tenga la extensión .txt o cualquier otra. El nombre del archivo debe ser config únicamente.

Ahora ábrelo con el editor de texto de tu preferencia (Bloc de notas, Editor, VSCode, Sublime Text, etc.) y escribe este contenido, poniendo el nombre de tu empresa en lugar de "devu":

# Configuracion de GitHub para mi cuenta Personal
Host github.com-personal
  HostName github.com
  User git
  IdentityFile ~/.ssh/personal/id_rsa

# Configuracion de GitHub para mi trabajo en Devu
Host github.com-work
  HostName github.com
  User git
  IdentityFile ~/.ssh/work/devu

Guarda los cambios y cierra el archivo.

Presta mucha atención a este detalle. Estamos usando un Host github.com-personal y un Host github.com-work. El sufijo -personal y -work le servirá a Git para escoger qué keys usar más adelante.

Además, el IdentityFile de cada configuración debe coincidir con los nombres de las carpetas y keys que creamos.

3. Configurar el remote origin del repositorio

Si vas a clonar/descargar el repo por primera vez

Escribe en la terminal el comando de git clone, pega la URL de tipo SSH, y modifícala para que el host quede como github.com-work si es un repo de tu cuenta del trabajo, o github.com-personal si es tu repo de la cuenta personal.

git clone git@github.com-work:ChemaCLi/git-tricks-and-tutorials.git

Si ya tienes el repo clonado/descargado

Escribe en la terminal los siguientes comandos para navegar a tu repositorio, verificar la URL del remote origin, y modificarla para que utilice la configuración work que definimos en el paso 2.

Para este ejercicio usaré un repositorio llamado "git-tricks-and-tutorials", y tú deberías usar el repositorio que te interesa configurar.

# Navegar al repositorio
cd ~/Documents/work/git-tricks-and-tutorials/

# Verificar el remote origin
git remote -v
# Aparecerá algo como esto
# origin    git@github.com:ChemaCLi/git-tricks-and-tutorials.git (fetch)
# origin    git@github.com:ChemaCLi/git-tricks-and-tutorials.git (push)

# Modificar la URL para que ahora use el host github.com-work
git remote set-url origin git@github.com-work:ChemaCLi/git-tricks-and-tutorials.git

Ahora verifica la nueva configuración del remote origin de Git.

git remote -v
# origin    git@github.com-work:ChemaCLi/git-tricks-and-tutorials.git (fetch)
# origin    git@github.com-work:ChemaCLi/git-tricks-and-tutorials.git (push)

Y finalmente valida que puedas comunicarte con GitHub haciendo git pull:

git pull --ff
# Already up to date.

Si te arroja un error, por favor escríbelo en los comentarios y responderé de inmediato para ayudarte y corregir la guía.

4. Settear firma de Git para el repositorio actual

Último paso para detalles finos. Si has logrado llegar hasta aquí, felicidades! solo nos queda un pequeño detalle más para contar con una configuración completa.

Vamos a hacer que el nombre y el email que aparecen en cada commit sea diferente para nuestro repositorio (en este caso el repo del trabajo)

Ingresa estos comandos para settear tu firma para el repositorio del trabajo:

git config user.email chema@devu.community 
git config user.name ChemaCL

Verifica la configuración con el comando git config --list:

# Esta configuración aparecerá hasta abajo
remote.origin.url=git@github.com-work:ChemaCLi/git-tricks-and-tutorials.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.main.remote=origin
branch.main.merge=refs/heads/main
user.email=chema@devu.community
user.name=ChemaCLi

Lo lograste! a partir de ahora cuando hagas pull o push usarás la SSH de tu trabajo para el repositorio del trabajo, y firmarás tus commits con los datos de tu trabajo.

Ahora intenta configurar el remote origin tus repositorios de tu cuenta personal para que usen la ssh de la carpeta personal. Puedes lograrlo siguiendo el paso 3 de esta guía. También recuerda que debes modificar el remote origin de todos los repositorios que hayas clonado. Pero descuida, solo tienes que hacerlo cuando lo necesites, no vayas a enloquecer.

Si algo falló, revisa bien tus configuraciones para descargar errores en los nombres de archivos y carpetas.

Si tienes dudas, correcciones o sugerencias, envía tus comentarios de manera respetuosa y los atenderé en cuanto me sea posible. Éxito!

Cambiar de HTTPS a SSH

Lo primero que debes hacer es verificar si ya tienes configurada una key SSH antes de continuar. También tendrás que asegurarte de configurar la key en la cuenta de GitHub del repositorio que estás intentando cambiar.

Para ello te recomiendo seguir esta otra guía a partir del paso 3:

Cómo instalar y configurar Git y SSH con GitHub en Mac, GNU/Linux o Windows (GitBash)

José María CL ・ Jan 9 '22

#git #github #tutorial #español

Cuando tu key SSH esté configurada en GitHub, lo siguiente es dirigirte a tu repositorio en GitHub, buscar la opción Clone y copiar la URL ssh.

En este caso mi URL para trabajar con SSH es esta:

git@github.com:ChemaCLi/git-tricks-and-tutorials.git

Ahora debes navegar al directorio en donde se encuentre clonado tu repositorio y asignar la nueva URL al remote origin.

git remote set-url origin git@github.com:ChemaCLi/git-tricks-and-tutorials.git

Listo, ya estás usando ssh a partir de ahora. Para verificar la configuración escribe el comando git remote -v y deberías ver una salida como la siguiente:

git remote -v
# origin    git@github.com:ChemaCLi/git-tricks-and-tutorials.git (fetch)
# origin    git@github.com:ChemaCLi/git-tricks-and-tutorials.git (push)

Recuerda que un remote es simplemente un repositorio remoto con el que te puedes comunicar para sincronizar cambios. Y el remote llamado origin es simplemente el remote principal.

Un buen libro para aprender y educar en programación

José María CL — Fri, 14 Jun 2024 02:51:23 +0000

Hola. Recientemente he estado dandole forma a contenido educativo para enseñar programación y dar unas mentorías. Y de paso, para recordar y reaprender los fundamentos.

En un punto me dio por recordar cómo fue que yo empecé a aprender, y cómo fue mi proceso 🤔.

Definitivamente no fue algo que podamos llamar "straightforward" 😅. Estaba muy confundido y siendo honesto, me aterraban los temas complejos. Muchos de esos temas complicados los evité por años con la esperanza de algún día entenderlos. En general, no sabía qué hacer para aprender a programar 🤷🏻.

✨ Un golpe de suerte

Entre tantas cosas que fui tomando de internet y decifrando en las clases de la ing. en sistemas, un buen día tuve la suerte de ir con unos amigos a una feria del libro en Orizaba (FILO) y encontré un libro llamado Programación Orientada a Objetos con C++ y Java 😀.

Estaba totalmente sellado y costaba unos 17 dólares (precio de hoy en 2024). Eso era un poco más de lo que disponía semanalmente, pero tenía la esperanza de que mis dudas se aclararían ahí, o al menos tener algo de dirección.

🌱 Una eventual y agradable sorpresa

El chiste es que a los pocos días pude conseguir lo suficiente y lo compré. Llegué a casa y me llevé una sorpresa al abrirlo. ¡Traía un CD, que lujo! jaja.

En realidad la sorpresa fue que el libro no enseñaba a programar directamente como otros recursos pretendían en la época (2016). Este libro más bien tenía la intención de involucrar las disciplinas esenciales de la programación y la ing. de software, para prepararnos como ingenieros de software y no solo como codificadores.

🌳 Cómo influyó en mi formación

El nombre completo del libro es Programación Orientada a Objetos con C++ y Java, un acercamiento interdisciplinario, por los autores Jose Luis Lopez Goytia y Angel Gutierrez Gonzalez, profesores en el Instituto Politécnico Nacional (en México es una de las escuelas más importantes.)

Hoy que lo he recordado, y vuelto a leer en The Internet Archive (porque lo presté y no ha vuelto a mis manos) me doy cuenta de que los capítulos 1-3 me "educaron" bajo su metodología al abordar problemas que necesitan ser resueltos con software.

No me había dado cuenta de que al día de hoy tengo interiorizados varios del los principios que el libro presenta.

Sin darnos cuenta, el libro funje como un curso profesional en el que aprendemos a crear software metodológica y estratégicamente, llevando a cabo buenas prácticas al analizar, diseñar, codificar y verificar.

🧑🏻‍🏫 👩🏻‍💻 ¿Por qué y a quién lo recomiendo?

Este es un libro que personalmente recomiendo para las personas que empiezan la carrera de ing. de software o de sistemas, y a quienes quieren aprender a programar profesionalmente. Para hacer el software de calidad que todos anhelamos y amamos, no basta con ser buen codificador, se necesitan formas, guías y disciplina a las cuáles recurrir cuando la duda de si estamos haciendo bien algo aparece, cuando la "motivación" o la "creatividad" se ausentan un momento.

Y aún más, este libro lo recomiendo mucho para los docentes que quieren formar profesionales del software. De hecho, este es uno de los enfoques de la obra. Es casi una propueta de Framework para la educación de profesionales del software.

📚 🏛️ Leer gratis

Puedes leerlo gratuitamente en The Internet Archive apartandolo por 1hra renovable si te creas una cuenta

Programación orientada a objetos C++ y Java : un acercamiento interdisciplinario : López Goytia, José Luis : Free Download, Borrow, and Streaming : Internet Archive

1 online resource (298 pages)

archive.org

No olvides compartir tus comentarios, opiniones o dudas en los comentarios :)

Si conoces o recomiendas otras obras puedes compartirlas también. Yo con gusto las leeré.

Happy Programmers' Day!

José María CL — Thu, 14 Sep 2023 07:04:46 +0000

El día de hoy (13 de septiembre del 2023) se celebra esta profesión, actividad, hobbie, o estilo de vida.

Para celebrar nuestro gusto por la programación realizamos unos pósters conmemorativos. Imprímelos, guárdalos, y compartelos!

Today (September 13, 2023), we celebrate this profession, activity, hobby, or lifestyle.

To celebrate our love for programming, we have created some commemorative posters. Print them, keep them, and share them!

Full size

How to render card items in sequence after data load is finished like AirBnB?

José María CL — Fri, 15 Jul 2022 18:28:32 +0000

When in AirBnB you scroll down to load more results I have seen that the cards load their data from start to finish like a dominoes style... like a sweep

Do you know what that effect is called or how to do something similar?

https://www.airbnb.ca/

Dockerize Postgres: How to install Postgres with Docker

José María CL — Sun, 01 May 2022 19:25:59 +0000

Hi. I'm about to take a CubeJS tutorial to create a nice dashboard and it seems that I need a Postgres DB.

So it's obvious that I have to use docker as usual and I want to share how to install Postgres in Docker because I wish someone had instructed me how to do it and save some time.

I will show you 2 ways to do it: the very simple way (single line command), and the most common and accepted way (using docker-compose.yml file).

One thing you have to know is that the container will be installed in the path you currently are, so I suggest you to create a directory for your project and create the container there.

1. Install it with the command line

Use the command below to install the postgres "image". You should customize it.

❯ docker run -p 127.0.0.1:5442:5432/tcp  -e POSTGRES_PASSWORD=mysuperpassword --name postgres_cube -d postgres:12

Once you ran that command, your terminal will show you something like the code below. This is the container ID which means it's up and running.

❯ 90a63c0aa9b597d63f644ecd178e549f161d12fa84d7a16a47545aaa92087124

To verify the container is up and running just run this command and you should see the postgres_cube is Up

❯ docker ps -a
CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS                     PORTS                    NAMES
17a8bca60f6d   postgres:12   "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes               0.0.0.0:5442->5432/tcp   postgres_cube

Command explanation

The docker run command first creates a writeable container layer over the specified image, and then starts it. Read more
The -p 127.0.0.1:5442:5432/tcp part specifies the port option to map the host (the real machine) port to the container port. Put attention on the 5442:5432. In this case I'm specifying that I want to use my machine 5442 port to connect with the container 5432 port (which is the postgres service port living in the container). I'll use the 5442 to connect my DB Client (DBeaver in my case). Read more about published ports
The -e POSTGRES_PASSWORD=mysuperpassword part specifies the environment variables that the image can detect. You should read the postgres image docs to see a complete list but the most common are:

- POSTGRES_DB
- POSTGRES_USER
- POSTGRES_PASSWORD

For postgres the POSTGRES_PASSWORD is required.

In this case I'm specifying the required POSTGRES_PASSWORD to set a password. The user by default is "postgres" and the default database is "postgres" and other 2 template databases (as usual).
--name postgres_cube specifies a custom name for the container. postgres_cube in my case. If you don't pass it, docker will use a random name but it's a good idea to give it a name to identify your container when using just a few of them
The -d is an option that allows us to detach our terminal session, which means that we don't need to keep a terminal open while the container is running.
And finally, the postgres:12 is the image (postgres) name and the tag (12). This is useful to install a specific version. If the tag is not specified, you will install the latest version.

2. Use a docker-compose file

First step is to create a docker-compose.yml in your project folder.

After that, copy, paste and save the content below:

version: "3"

networks:
  net-cube-tutorial:

volumes:
  db-cube-tutorial:

services:
  postgres:
    image: postgres:12
    hostname: postgres
    restart: unless-stopped
    container_name: postgres_cube
    environment:
      POSTGRES_DB: cube_tutorial
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: mysuperpassword
    ports:
      - 5442:5432
    volumes:
      - db-cube-tutorial:/var/lib/postgresql/data
    networks:
      - net-cube-tutorial

Finally run the command below. Docker will look for the docker-compose.yml file at the current path automatically, so you don't need to worry about.

❯ docker-compose up  -d

Your terminal will output something like the messages bellow, which means everything is fine.

Creating network "cubejs_net-cube-tutorial" with the default driver
Creating postgres_cube ... done

To verify the container is up and running just run this command and you should see the postgres_cube is Up

❯ docker ps -a
CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS                     PORTS                    NAMES
17a8bca60f6d   postgres:12   "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes               0.0.0.0:5442->5432/tcp   postgres_cube

File structure explanation

What does the docker-compose.yml? Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. Read more about it
version: "3" specifies we will use the syntax version 3. Read more about compose versions
networks lets you to define container internal networks. This is perfect when you need to connect or join multiple services in the same container. Read more about networking
volumes is the virtual storage for the container if we wan't to keep the data. It's useful to set a name for it because it will let us to reference the services to use it. Read more about volumes
services is the list of the services will run on the container. Here we can specify a set of images and its configuration. In this case we only need the postgres service connected to the named container network, using the named storage and map the network port to our host port to be able to connect the DB with an external program outside the container.
image is the image name, in this case we need postgres. Also we can specify a tag, which is 12. If you don't specify it, it will use the "latest" version.
hostname lets you assign a name to the service as host in the network. It's useful if we want to allow services to communicate between them. We can use the host name to reference the services at network level.
restart specifies the restart policy. unless-stopped always restart the container if it stops, Similar to always, except that when the container is stopped (manually or otherwise), it is not restarted even after Docker daemon restarts.
container_name allow to set a name for the container so we can easily find it. If you don't give it a name, a randomly generated name will be used.
environment is the section where we are able to specify environment variables supported by the image. For postgres there is a list you can explore in the docs but the most common are
- POSTGRES_DB
- POSTGRES_USER
- POSTGRES_PASSWORD

I recommend you to avoid exposing the variable values in the docker-compose.yml. Instead, you should specify them in a .env file and use it in the docker-compose.yml in this way

*.env file: *

DB_USER=mypostgresuser
DB_PASSWORD=mysuperpassword

*docker-compose.yml: *

   POSTGRES_USER: ${DB_USER}
   POSTGRES_PASSWORD: ${DB_PASSWORD}

ports lets you map your actual machine (the host) to the container network ports. In this case I'm using the port 5442 of my machine to access to the container port 5432 to be able to connect DBeaver to the database directly.
volumes here we map the container folder called "data" (/var/lib/postgresql/data) to be accesible from the root of our volume named db-cube-tutorial
networks allow us to connect our service to the specified container network.

Bonus: Connect a DB client (DBeaver) to our DB

I'll use thee DBeaver program to easily use my DB, but you can use whatever you want.

Create a new connection with your own settings:

Test the connection
1. Enjoy

Cómo instalar y configurar Git y SSH con GitHub en Mac, GNU/Linux o Windows (GitBash)

José María CL — Sun, 09 Jan 2022 06:13:16 +0000

Hola. En este post describo los pasos para instalar y configurar Git, así como ajustarlo para trabajar con GitHub.

Si usas Windows, instala Git con el instalador gráfico, asegúrate de poner el check para que igual se instale GitBash, reinicia la PC y usa el GitBash en lugar de la terminal para seguir la guía sin problemas (al menos con pocos).

Siempre que es posible trato de usar Brew para instalar las aplicaciones que quiero. Es útil para mantener las cosas actualizadas. En este post escribí cómo instalar Homebrew en el primer paso.

Si usas alguna distro debian de GNU/Linux, solo usa el comando sudo apt-get install git en lugar de brew.

1. Descargar e instalar Git

Para instalar git manualmente podemos ir al sitio oficial de descargas. Hay instalador para Windows, MacOS y GNU/Linux.

Instalar con Brew:



~ ❯ brew install git

Verifica que Git esté instalado:



~ ❯ git --version
git version 2.30.1 (Apple Git-130)

2. Configurar Git

Después de verificar que Git está instalado tenemos que configurar las variables globales:

nombre de usuario (user) que aparecerá como autor de los cambios
email del usuario
editor que queremos usar para escribir los mensajes de los commits y demás cosas

Ingresa los siguientes comandos usando tus datos:



~ ❯ git config --global user.name "John Doe"
~ ❯ git config --global user.email johndoe@example.com
~ ❯ git config --global core.editor vim

Esos comandos los puedes volver a ingresar para actualizar las variables. Si en lugar de vim quieres usar otro editor, ingresa nano, code (visual studio code) u otro.

Verifica las variables:



~ ❯ git config user.name
John Doe

~ ❯ git config user.email
johndoe@example.com

También podemos listar todas las variables de la configuración:



~ ❯ git config --list
credential.helper=osxkeychain
user.name=John Doe
user.email=johndoe@example.com
core.editor=vim

Puedes leer más en los sitios oficiales de Git y de GitHub:

3. Generar llaves SSH

Para comunicarse con repositorios remotos como GitHub, GitLab o Azure podemos hacerlo de dos formas: con https o con ssh.

En este post describo el método con SSH.

Usar https es lo más fácil y actualmente es igual de seguro que ssh. Los leaks o filtraciones dependen de tí realmente.
Yo prefiero ssh por costumbre y porque no me gusta autenticarme en cada push o pull.

Si decides ir por la vía de https tendrás que configurar un GitHub Personal Token y usarlo para autenticarte. Dejo la guía de GitHub sobre cómo hacerlo.

Verificar si ya existen las llaves SSH:

fuente

Ingresa este comando para listar (ls) los archivos, especificando que queremos ver todos los archivos (-a) en forma de lista vertical (-l) dentro de la carpeta oculta .ssh que se encuentra en el directorio home (~/) del usuario:



~ ❯ ls -al ~/.ssh

Si ya tenías las claves te aparecerá algo como esto, en cuyo caso, puedes ir al paso 4:



total 48
drwx------   7 chema  staff   224 Dec 31 13:09 .
drwxr-x---+ 34 chema  staff  1088 Jan  8 23:00 ..
-rw-------   1 chema  staff  3401 Dec 31 13:10 id_rsa
-rw-r--r--@  1 chema  staff   755 Dec 31 13:10 id_rsa.pub

Si no las tienes, te aparecerá algo como esto:



ls: /Users/chema/.ssh: No such file or directory

Generar nuevas claves SSH:

fuente

Si no tenemos alguna clave SSH tendremos que generar un nuevo par de clave privada y pública, las cuáles se generan juntas:



~ ❯ ssh-keygen -t rsa -b 4096 -C "johndoe@example.com"

Nos preguntarán el nombre del archivo que tendrá, puedes presionar enter si quieres usar el nombre por defecto (id_rsa):



Enter file in which to save the key (/Users/chema/.ssh/id_rsa):

Después nos pedirán especificar una contraseña y confirmarla. Ésta se pedirá cada vez que nos comuniquemos con repositorios remotos con pull, push y demás.
También se puede presionar enter (dos veces para confirmar) si no queremos agregar ninguna.

Si tienes mucho cuidado con quién y cómo tienen acceso a tu equipo puedes ir sin contraseña). Cuando introduzcas la contraseña no se verá lo que escribes pero sí está escribiendo:



Enter passphrase (empty for no passphrase):
Enter same passphrase again:

4. Agregar claves SSH a la cuenta de GitHub

Ve a github.com, inicia sesión o crea una cuenta (no olvides confirmar el email) y busca la opción Settings que nos llevará a la página de ajustes:

Busca la opción de SSH and GPG Keys en la barra lateral izquierda:

Selecciona la opción para agregar la clave SSH que abrirá un formulario para que introduzcamos el nombre de nuestra clave SSH (el nombre que gustes) y para que "pegues" la llave pública, es decir, el contenido del archivo id_rsa.pub:

Para ver y copiar el contenido del archivo id_rsa.pub tenemos dos opciones:

podemos usar el Finder de Mac o el buscador que tengamos
mostrar el contenido en consola y copiarlo

Con el finder

Accede a la carpeta de tu usuario, presiona Shift + Cmd + .. para mostrar archivos ocultos, busca la carpeta .ssh y accede. Verás unos archivos como estos:

Abre el archivo id_rsa.pub con el editor de texto de tu preferencia, copia todo el contenido y pégalo en el formulario de GitHub.

Con la terminal

Escribe lo siguiente para usar el comando cat (concatenar) el cuál mostrará el contenido en la consola:



~ ❯ cat ~/.ssh/id_rsa.pub

Finalmente copia el texto en consola y pégalo en el formulario de GitHub.

5. Clonar un repositorio con SSH

Bien, eso fue todo. Ahora intenta clonar algún repositorio para verificar que las cosas hayan salido bien. Puedes clonar este repo si gustas.

La primera vez nos advertirán que se guardará la huella (fingerprint) del host remoto como conocido y tendremos que ingresar "yes" para continuar.



~ ❯ git clone git@github.com:ChemaCLi/git-tricks-and-tutorials.git

Services Layer approach in ReactJS

José María CL — Thu, 30 Dec 2021 01:32:29 +0000

Resume

In this post I want to show you a technique I'm trying to implement in order to decouple the implementation of REST, GraphQL or whatever you use to communicate your frontend with a backend (backend, storage, local files, etc).

Motivation

Hi there. I'm a web developer. I've some experience building apps with old techniques with PHP, Java and .Net C#. So I've saw ugly stuff and other things that makes the programming experience a pain: hard to maintain, hard to debug, hard to scale, hard to test (maybe impossible).

I've been working with ReactJS since some years ago and I noticed something that caught my attention. Most developers are making the same mistakes we made in the past (me included of course).

I'm talking about spaghetti code, untestability, and implementation coupling.

So, well, I know there are some principles we can apply to make things easier (I'm talking of SOLID, DRY, KISS, etc.) and I want to make it better.

Services Layer approach

Ok, when we write a react component that will use some service connection we tend to do it in this way for example

import axios from "axios";
import {useState, useEffect} from "react";

export function OrdersList() {
  const [orders, setOrders] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    axios.get("/orders")
      .then(({data}) => setOrders(data))
      .catch(e => console.error(e))
      .finally(() => setLoading(false));
  }, []);

  return (
    <ul>
      {orders.map(order => (
        <li key={order.id}>{order.id}</li>
      ))}
    </ul>
  );
}

It looks fine, didn't? But then if you have more components that implements the same endpoint? what if the endpoint changes? you will have to update it on each component. Also, when you need to add more treatments to the data like mapping or normalization, you will add more code. And finally, if you want to add an unit test you will probably use an axios mock strategy.

My proposal is to encapsulate the data fetching in a collection of functions (near to be repositories) that receive arguments if necessary and that returns the needed data.

async function getAll() {
  const result = await axios.get("/orders");
  return result.data || [];
}

export const ordersService = {
  getAll
};

Now we can use it in this way using dependency injection.

import {useState, useEffect} from "react";

// the ordersService is injected (dependencies injection)
export function OrdersList({ ordersService }) {
  const [orders, setOrders] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);
    ordersService.getAll()
      .then(orders => setOrders(orders))
      .catch(e => console.error(e))
      .finally(() => setLoading(false));
  }, []);

  return (
    <ul>
      {orders.map(order => (
        <li key={order.id}>{order.id}</li>
      ))}
    </ul>
  );
}

and with that dependency injection we can easily write a mock no matter what kind of service we use (rest, graphql, etc) because only the "orders service" knows what is the magic behind

it ("Loads two orders") {
  const mockOrdersService = {
    getAll: async () => ([{ id: "mock-01" }, { id: "mock-02" }])
  }

  const { getByTestId } = render(<OrdersList ordersService={mockOrdersService} />);
  ...
}

Right now it seems very simple, and I'm happy for that. But I want you to see more advantages.

Please think you have to create a new order. You will use a post request, and the backend needs a specific payload.

{
  order: {
    notes: "Extra cheese",
    items: [{ sku: "hamburger-01" }]
  },
  customer: {
    customer_id: "01",
    registered_customer: true,
    not_registered_customer_name: null
  }
}

In this case we can add a new function at the service layer in this way:

async function sendOrder({
  notes,
  items,
  client_id,
  not_registered_customer_name = null
}) {
  const data = {
    order: {
      notes,
      items
    },
    customer: {
      customer_id,
      not_registered_customer_name,
      registered_customer: !!customer_id
    }
  };

  const result = await axios.post("/orders", data);
  return result.data || null;
}

export const ordersService = {
  getAll,
  sendOrder
}

Now if we need to create the order we just pass the needed arguments and the function will format the data

ordersService.sendOrder({
  client_id: "01",
  notes: "Extra cheese",
  items: [{ sku: "hamburger-01" }]
});

With this approach we are decoupling the implementation details, avoiding code repetition, allowing the testability. And just by separating the code concerns.

Then, I would like to talk about the separation of logic from the UI by using react Hooks and a hook I've designed to work like the graphql useQuery hook (I love that hook, but causes hard to maintain code)... but I think it's better to wait for your feedback in order to give a better proposal.

Also, you can give me some feedback about my writing on english. I will appreciate it a lot. Peace! ✌️

Instalando ZSH en Mac

José María CL — Sat, 04 Dec 2021 07:07:54 +0000

Hola. En este post describo los pasos que sigo para instalar iTerm, ZSH, oh my ZSH y algunas configuraciones de los temas para la consola. Ojalá te sirvan.

1. Instalar Homebrew

Sé que podemos instalar todo lo necesario directamente pero Brew nos ayudará a ahorrar algo de tiempo y a mantener nuestros paquetes actualizados.
Visita https://brew.sh/ para seguir las instrucciones más recientes. Los pasos se pueden resumir en:

Pega este comando para descargar y ejecutar el instalador



/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Nos solicitará la contraseña de usuario y esperará a que presionemos ENTER para iniciar la descarga.
Nota: Por defecto Brew siempre intenta actualizar todos los paquetes antes de instalar cualquier cosa.

2. Instalar iTerm2

Esta terminal nos ofrece varias características interesantes que la terminal por defecto no tiene como múltiples pestañas acopladas, hotkeys, autocompletado, búsquedas, detección de errores en los comandos y más. Este es su sitio oficial https://iterm2.com/index.html

Para instalarla con Brew



brew install iterm2

3. Instalar ZSH

Uso ZSH en lugar del Bash por defecto porque nos ofrece la posibilidad de instalar plugins y temas entre otras cosas que facilitan la navegación y detección de errores mientras escribimos. Esta es su web https://www.zsh.org/



brew install zsh

4. Instalar Oh My ZSH

Esto es un framework que ayuda a configurar ZSH. Sirve como una capa que nos hace las cosas más sencillas.
https://ohmyz.sh/
No necesitamos usar Brew porque esto no es un programa funcional por sí solo, sino que es un framework con un set de helpers y funcionalidades extra para ZSH.

Copia y pega esta línea para descargar y ejecutar el archivo de instalación install.sh:



$ sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Para verificar que esté instalada podemos checar la versión



zsh --version

5. Instalar el tema Powerlevel10k

Es un tema popular. Tiene buen aspecto y nos brinda un configuración que a la mayoría nos queda bien.

Este es el repo de GitHub donde está el tema y las instrucciones para instalarlo https://github.com/romkatv/powerlevel10k#installation

Descárgalo para Oh My ZSH



git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Busca el archivo de configuración de .zshrc que está en tu directorio Home. Es un archivo oculto, así que si no lo ves tendrás que presionar cmd + shift + .

Cuando lo encuentres ábrelo con tu editor de texto plano preferido, busca la línea que dice ZSH_THEME="robbyrussell", coméntala y agrega lo siguiente para reemplazarla:



# ZSH_THEME="robbyrussell"
ZSH_THEME="powerlevel10k/powerlevel10k"

Guarda los cambios y cierra la terminal.

6. Configurar Powerlevel10k

Después de cerrar la terminal, abre iTerm2. Verás algo similar a esto:

Ingresa y si quieres instalar la fuente recomendada, n si no quieres. Después reinicia la terminal.

Cuando la vuelvas a abrir se mostrará un Wizard para hacer algunas calibraciones. Esto sirve para que detecte la codificación correcta del texto y no muestre símbolos raros.

Al terminar la calibración te preguntará qué estilo prefieres. Yo escogeré Lean porque no me gustan tantos colores:

En los siguientes pasos escogeré Unicode, 256 colores, que no me muestre la hora, ver el "prompt" en la misma línea, segmentos compactos, muchos íconos, conciso, no habilitaré el prompt fluído, y habilitaré el prompt instantáneo porque no me gusta que se va lag al abrir al terminal. (leer más)

Finalmente aplica los cambios en la configuración. Verás algo similar a esto de acuerdo a la configuración que hayas escogido:

Esto es todo por ahora. En siguientes entradas agregaré cómo personalizar más ZSH y iTerm con unos plugins y un par de configuraciones.

Java Programming Handbook

José María CL — Sun, 14 Mar 2021 17:26:03 +0000

This post is part of the Object Oriented Programming Notes series I'm still writing. It's intended to be a quick handbook for people who need or want a language overview and see how to write some code.

There is a running example at the end of the post.

If you need a full amazing Java tutorial/course/guide, please visit this page I found while I was studying about access modifiers:

http://tutorials.jenkov.com/java/index.html 🚀

You won't find how to install anything or how to setup you development environment here by the moment, but you can test code using replit.com to start coding Java online ;)

☕ Java Overview

In this section you will find some information about the Java language. But if you want a deeper understanding, please read the Thinking in Java book by Bruce Eckel if you already know some programming basics.

📓 What is Java?

Java is a Programming Language designed to allow programming under the Object Orientation Paradigm.

Like any other language, it offers a set of special words and some rules to form logic sentences that others can understand. The main goal of the Programming Language is to allow you to write sentences the computer can understand in order to perform actions.

You can write a group of instructions to create processes, then create a group of processes to create programs, and then create a group of programs to create a system.

There are some words for a specific usage. These words are known as reserved words. Also, there are two main set of rules: the syntax and the semantics. The syntax defines how to write sentences in the right way, and the semantics defines the structure of the code in the right way so the computer can understand your instructions.

🤖 Strongly typed language

Java is a strongly typed language. This means that Java needs you to define the type of every data you declare.

Because the way a computer works is by reading data from memory (from Hard Disk or RAM) to use it in processes running in the CPU, we need to separate a place in the memory for every variable and temporary data to ensure our program works fine.

Every data type has a size in bits (physical slots in memory). So, when we declare the data type of a variable, for example, we are telling the computer to ensure the right space to store our data in memory to avoid errors like insufficient memory space.

There is a set of data types: numbers, strings of characters (text), single characters, booleans (true or false), objects (data structures), etc.

You can read more about strong and weak typed languages here.

🔮 The magic

One more thing. The computer just understands binary instructions (0 and 1, the machine language). This is called low level language. Low is near to the machine language, and hight is near to human language.

Java is a hight level language, so we need to translate our hight level instructions to low level instructions. Fortunately, there's a program that do the dirty job.

This program is called "compiler". It translates a hight level language to low level language.

There exists another programs called "transpilers" which translates a language to other language in the same level.

However, in this case we need a "compiler" to compile (translate to low level) our Java code to machine language.

The compilers and the transpilers have internal mechanisms which allows to check if the code syntax is ok and it respects the semantic rules. So, the compiler won't leave to compile or run code with syntax and semantic errors. But remember, you can write code with logic errors with well written instructions.

👩‍💻 Writing Code

In this section you will find a reference about the basics to write Java code. Feel free to re-visit it when you need to.

Comments

Comments are a way to write things in the code that will be ignored by the computer. Comments don't have any functionality.

It's recommended to write comments to explain something about the code if necessary. Usually, we use comments to "document" the code, to help other programmers to quickly understand a process, or to explain certain specific concepts that are not common.

When you are learning is ok to write many comments to add notes, but when you are working on a more serious project you should avoid to abuse of this resource. To avoid unnecessary comments try to write the code as simple and understandable as possible. If you want to know more, google about clean code and good practices.

/**
 * ✅ This is a multiline comment
 * so you can write a very long comment.
 * This format is used to document your code.
 */

/* ✅
This is a valid  multiline
comment
*/

/* ✅ as well as this one*/

// ✅ This is an inline comment. You can't use multiline
because this line won't be interpreted as a comment ❌

Semi-colon and Curly braces

This is the semicolon symbol ;, and these are the curly braces {}.

Semicolons are used to specify the end of an instruction, and curly braces are used to specify an scope.

Semicolon usage examples:

// ✅ method execution ends until the semi-colon appears
sendAnEmail("hey@well.com");

// ✅ declaration ends until the semi-colon appears
String thisWillStoreMyDogName = "Pulgas";

/**
 * ❌ In this line I forget to write a semicolon after "Florencio"
 * so the Java compiler will understand that these two lines are the same
 * instruction, so the instruction:
 *  
 * String myFishName = "Florencio"String myDogAge = 4;
 *
 * doesn't make sense to the compiler and will be marked
 * as an error
 */
String myFishName = "Florencio"
String myDogAge = 4;

public String sendAnEmail(String email) {
  // ✅ return statement ends until semi-colon appears
  return "Message sent to: " + email;
}

public String sendAnSMS(String phone) {
  // ❌ Java will read the sentence as:
  // return "Message sent to: " + phone }
  // so it doesn't make sense to the compiler
  // if a curly brace } appears at the end of a return
  // statement. So don't forget the semicolons never!
  return "Message sent to: " + phone
}

Curly-braces also wrap your pieces of code to allow to reuse your logic and to create named processes called methods. You will use {} to write the definition of your classes and methods inside, and for some statements like loops and comparisons.

The {} defines a scope, so you can access to anything that is inside the {}, but if there is something out, you won't be able to access to it.

Curly braces usage examples:

public class Cellphone { // your class scope starts here

  // ✅ These variable will be available for all the methods 
  // inside the class curly braces {}
  public String myCatName = "Bigotes";


  public String getCatName() { // method scope starts here
    // ✅ You can access to the variable at class level from the 
    // method using the special word `this` only if the
    // method is under the class scope defined by the class 
    // curly braces
    return this.myCatName;
  } //  method scope ends here


  public String getDogName() { // method scope starts here
    // ✅ You can access to the variables inside the {} of the method
    String myDogName = "Pulgas";
    return myDogName;
  } // method scope ends here


  public String getMyDogName() { // method scope starts here
    // ❌ This method will cause an error because it doesn't know 
    // about the variables of other methods that are out of
    // its scope
    return myDocName;
  } // method scope ends here


} // class scope ends here

Types

Java is a strongly typed language. We need to specify data types to tell Java what kind of values we are working with. Thanks to this, the values are more predictable and it's possible to ensure the memory space to store our data.

Analogy: If I tell you that the variable x stores a number, and the variable y stores another number, when we sum x + y we can infer that the result will be a number. But if you don't know what kind of data the variable y stores, you won't be able to know if it's even possible to sum it with x. The Java compiler has the same problem, so it needs our help to specify the data type of the variables.

I'll copy and paste some examples from w3schools.com, but you should read more about here.

int myNum = 5;             // Integer (whole number)
float myFloatNum = 5.99f;  // Floating point number
char myLetter = 'A';       // Character
boolean myBool = true;     // Boolean
String myText = "A text";  // String

Access modifiers

Remember that Java is an Object Oriented Programming Language. One of the main concepts of the OOP is encapsulation. The access modifiers are a Java feature that allows us to encapsulate objects behaviors (methods) and data (variables).

Very basically, the access modifiers are key words that specify the visibility (exposition or availability are good terms too) of variables and methods.

Note: the variables and methods of a class are know as members of a class.

public: Makes members available outside the class. Can be inherited to the sub-classes (inheritance is another key concept of OOP) and outside the package.
private: Makes members available only inside the class. The members cannot be inherited to the "subclasses", and are not available from outside the package.
protected: Makes members available only inside the package of the class, and for subclasses even if the subclass is outside the package.
default: Makes the class members accessible at package level only. Subclasses can inherit protected members only if it's inside the package.

public class MyPublicClass {
  // This variable is accesible inside the class  only.
  private myDogName = "Pulgas";

  // This method is accesible from the outside of the class and package
  public void getFirstLetterOfMyDogName() {
    String letter = this.myDogName.substring(string.length() - 1);
    return formatText(letter);
  }

  /**
   * This method is for internal usage in the class only.
   * We don't want others to know what we are doing here.
   */
  private String formatText(String text) {
    return "Your dog's name first letter is: " + text.toUpperCase();
  }

  /**
   * This method is accessible at package level
   * or available to sub-classes
   */
  protected void sayHello() {
    System.out.println("No, I will say goodbye!");
  }

  /**
   * This method has a default access modifier, so
   * it will be available at package level only,
   * and for subclasses inside the package.
   */
  void sayHello() {
    System.out.println("Goodbye!");
  }
}

Let's see what happens when we try to access to the class variables and methods:

// First of all, lets create an object based on the MyPublicClass
MyPublicClass objectInstance = new MyPublicClass();

// ✅ Now that the object exists, lets execute this public method
objectInstance.getFirstLetterOfMyDogName();
// It works fine because the method is public, so we can access from the outside

// ❌ But this method execution is not possible because the method
// is privated and it's not available for external usage
objectInstance.formatText();

// ❌ Trying to access to a private class variable isn't possible either
objectInstance.myDogName;

I found this great page. You can check it out for a deeper explanation.

Variables

Variables allow you to store data temporary in the computer memory. They are very useful to make operations. You can set them values over and over again.

Creating a variable is known as variable declaration.

You can declare variables inside a "class" or inside a "method". When the method is finished or the class instance is collected by the Java Garbage Collector (a Java mechanism to remove useless stuff from the memory) the variable will be removed from memory and you won't be able to use it anymore.

This is the way to declare a variable:
[type] [variableName] = [value];

Variables declared at Class level must have an access modifie):
[visibility] [type] [variableName] = [value];

The variable names must be in camelCase which is a style by convention (a convention is a style everybody follow).

// ✅ Declare a variable without an initial value.
// You can't use it until you set it a value
int age;

// ✅ You can declare many variables in a single line
// if all them are of the same type
String address, email, website;

// ✅ You can set a value to the variable in this way
age = 25; // the "=" is called assignation operator

// ✅ Declare a variable with an initial value
String name = "unknown user";

// ✅ You can set a new value later
name = "Sara";

// You must set compatible types
// ✅ This is valid
boolean isAnAdult = true;

// ❌ But this is not valid because "nop" is a String
// and isAnAdult was declared as a boolean type variable
isAnAdult = "nop";

// ✅ Class level variables are declared in this way
public String myName = "Unknown";
private String myDog = "Pulgas";
protected String myCat = "Bigotes";

Methods

A method is a code structure that allows you to wrap some instructions as a single process you can execute whenever
you want and all the times you want. Methods will perform your awesome instructions when you execute them. Until that, they will be sleeping (inactive).

This is the way to execute a method: doSomething(); . As you can see, you only have to write the method name followed by two parenthesis ().

A method is a bit more complex than a variable because it can do more: it performs the instructions you write inside it.

A method can receive many values (or no one), and return values (or nothing).

This is the way to send values to the method:
doSomething("with this text");

This is the way to receive values from a method:
String receivedValue = giveMeAValue();

The values that the method can receive are called "parameters" or "arguments" (params and args in short). You must specify the type of each arg. Also, you must specify the type of the value you will return (use void if you won't return anything).

You can execute a method from inside another method, so you are able to have multiple simple methods to do an specific task and combine them to create a more complex process.

This is the structure to declare a method:

[access modifier] [return value type] [methodName]([args]) {
  ...method definition
}

Let's see some examples:

public void doNothing() {
 // ✅ nothing will happens when you execute this method
}

// ✅ This method don't return anything so we declare it as void
// Also, this method doesn't receive any arg, so we keep the () empty
public void saySomethingNice() {
 // your instructions go here..
 System.out.println("Hi there! You are a nice person!");
}

/**
 * ✅ This method will return a text with the planet name
 * so we specify String as the return type.
 * Also, this method doesn't receive any arg, so we keep the () empty
 */
public String giveMeThePlanetName() {
  return "Earth";
}

/**
 * ❌ This method will throw an error because the method
 * return type is specified as void, so the Java compiler
 * won't allow to return anything, but you are trying to
 * return something
 */
public void giveMeTheCountryName() {
  return "I don't know";
}

/**
 * ✅ This method will return a number with the result of a sum
 * so we specify int as the return type.
 * Also, this method receives two args, both int numbers
 */
public int sumTwoNumbers(int numberA, int numberB) {
  int result = numberA + numberB;
  return result;
}

/**
 * ❌ This method will throw an error because the method
 * return type is specified as int, so the Java compiler
 * expects a compatible return value, but you are not returning anything
 */
public int giveMeThisPostYear() {

}

/**
 * ✅ You can combine methods
 */
public void sum1and3() {
  const myResult = sumTwoNumbers(1, 2);
   // System.out.println method writes a text in the console
   // you can see a running example in the Classes section
   System.out.println("This is the result: " + myResult);
}

The if - else Conditional Statements

These utilities are very useful to validate data and to define processes that have different behavior depending on a condition. E. g. if you are building a login to allow and block access to the platform, you will need to validate if the user and password are correct. If yes, allow to access. If not, deny the access.

// ✅ This is the common way to use the if-else statements
if (true) {
  // the condition was fullfilled
} else {
  // the condition specified in the if was not fullfilled
}

// ❌ You can't use only the else statement alone because it depends on the if statement defined rules
else {

}

// ✅ But you can use only the if
if ((2 + 2) == 4) {
  System.out.println("Mathematics are right");
}

// ✅ You can omit the curly braces {} if you only have one line per statement
if (1 < 8)
  System.out.println("1 is less than 8");
else
  System.out.println("1 is not less than 8, it could be equals or bigger");


/**
 * ❌ Java compiler will detect an error here because se second System.out,println
 * is not part of the if statement and then it finds the else statement after something that is not
 * an if statement
 */
if (1 < 8)
  System.out.println("1 is less than 8");
  System.out.println("isn't ok?");
else
  System.out.println("1 is not less than 8, it could be equals or bigger");

// ✅ You can fix it in this way
if (1 < 8) {
  System.out.println("1 is less than 8");
  System.out.println("isn't ok?");
}
else
  System.out.println("1 is not less than 8, it could be equals or bigger");

Classes

This is the more complex part. This is a key feature of the Java Object Orientation implementation.

A class is a data structure that wraps a set of functionalities as methods (behavior) and data as variables (state).

You can think about classes as a blueprint that allows you to define an object.

Supose we are creating a bot for telegram or facebook messenger to allow some users in a group to randomly choose a place to get a good time after work. How to program it? Where to start?

Well, first of all we have to think what entities are really important. In this case, the two main entities are the User and the Bot.

Nice, looks not very complicated. Let's model the Bot, let's make the Bot blueprint (Bot class).

// The first step is to declare our blueprint (our class).
// In Java, all the classes name must be in PascalCase, the first letter must be capital
public class Bot {

}

Ok, now, our Bot needs some data to do some actions. Let's add some configuration data:

We want to allow to the group admin user to configure the day of the week and the hour, and allow to the rest of the users to propose a place the bot will choose from.

So, we have to declare the variables to store the object data, which is know as object state:

public class Bot {
  /**
   * These variables are private because are for internal usage
   * we don't want and don't need to make them accesible.
   * Remember to expose just the very needed and useful data
   * and functionalities.
   */
  private String botName; // can store a single string: "Mr Bot"
  private ArrayList<String> proposedPlaces = new ArrayList<String>(); // can store a group of texts: ["Beerhole", "Sam's Bar and Wine", "Super Taco"]
  private String dayOfWeek; // can store a single string: "Friday"
  private String hour; // can store a single string: "5:00pm"

}

Nice! Now we have variables to store our data when the Bot is created.

Next step is to define the behavior. So, what do we need? I think we need to create a functionality to configure the Bot name, set the day and hour, save the proposed places, and randomly choose a place.

There is a special method which allows us to do something when the object is created. This method is called constructor because it's executed while the object construction process.

How an object looks like? How do we create it? you might ask. Well, we create an object based on the class that defines it. To do so, we will write something like this:

Bot ourSuperBot = new Bot();

The above line is declaring a variable of type Bot that will contain a new object instance of the Bot class (Bot type), which means that it's an object created and loaded in the memory of your computer based on the Bot class.

In other words, the Bot it's alive now! and we refer to it as ourSuperBot

You can create many objects based in the same class, and everyone will have different data. For example, you can create a bunch of bots of type Bot:

Bot ourSuperBot = new Bot();
Bot superBotBrother = new Bot();
Bot kevinBot = new Bot();

I wanted to show you that in advance because I want you to understand how the constructor method works.

Check out this part with attention: Bot();. It looks like a method, right? Well, in fact, it is. When we create a new object instance of a given class we can pass data through the parenthesis (), and this data will be received and handled by the constructor.

Ok, let's go back to our Bot project to see the constructor in action.

We want to configure our Bot approaching the constructor. The only configuration will be the Bot name, the day, and the time.

public class Bot {
  private String botName;
  private ArrayList<String> proposedPlaces = new ArrayList<String>();
  private String dayOfWeek;
  private String hour;

  // This is the constructor. The constructor must have the
  // class name and must be public. Also, it has not a return type 
  public Bot(String botName, String dayOfWeek, String hour) {
    // the word "this" allows you to access to variables at class level
    this.botName = botName;
    this.dayOfWeek = dayOfWeek;
    this.hour = hour;
  }

}

Great! Now we can configure the Bot when we create the new object instance in this way:
Bot ourSuperBot = new Bot("Mr Bot", "friday", "5:20pm");

Now we need to create a method to save the proposed places:

public class Bot {
  private String botName;
  private ArrayList<String> proposedPlaces = new ArrayList<String>();
  private String dayOfWeek;
  private String hour;
}

 public Bot(String botName, String dayOfWeek, String hour) {
    this.botName = botName;
    this.dayOfWeek = dayOfWeek;
    this.hour = hour;
  }

  // Must be public to allow to use it when the object 
  // instance is created. We don't need to return any value
  // so we declare it as void. We need to receive the place
  // as an string, and save it in the global variable
  public void proposeAPlace(String place) {
    // the add() method allows to add an item at the end of the list
    this.proposedPlaces.add(place);
  }

Lets add a method to get the randomly choosed place by the Bot:

public class Bot {
  private String botName;
  private ArrayList<String> proposedPlaces = new ArrayList<String>();
  private String dayOfWeek;
  private String hour;

 public Bot(String botName, String dayOfWeek, String hour) {
    this.botName = botName;
    this.dayOfWeek = dayOfWeek;
    this.hour = hour;
  }

  public void proposeAPlace(String place) {
    this.proposedPlaces.add(place);
  }

  /**
   * We need to return a string (the randomly choosed place)
   * so we declare the method return type as String.
   * We don't need to receive anything so we don't specify 
   * anything in the params. And that's all.
   */
  public String chooseAPlace() {
    Random rand = new Random(); // this is an special object of Java to make random things
    return this.proposedPlaces.get(rand.nextInt(proposedPlaces.size()));
  }

The method chooseAPlace()will return just the name of a random place, but we want to decorate it with a nice message like "Hi! This is Mr Bot. The winner this week is: Sam's Bar and Wine. Schedule this date to meet your friends: friday 5:20pm".

To do so, we need to add a new method to decorate the text before returning it, but this method will be for internal usage only, so should be private to avoid the users from using it.

It will receive a String (the place) via args, decorate the received String, and return it decorated.

Step 1: Declare the `private` method

public class Bot {

  ... // this means that there are more code above but we don't want to write it again in this piece of example code

  private String decorateText(String textToDecorate){
    String decoratedText = "The winner this week is: " + textToDecorate;
    return decoratedText;
  }

Step 2: Use our new `private` method

public class Bot {
  private String botName;
  private ArrayList<String> proposedPlaces = new ArrayList<String>();
  private String dayOfWeek;
  private String hour;

  public Bot(String botName, String dayOfWeek, String hour) {
    this.botName = botName;
    this.dayOfWeek = dayOfWeek;
    this.hour = hour;
  }

  public void proposeAPlace(String place) {
    this.proposedPlaces.add(place);
  }

  /**
   * We need to update our method to implement the new
   * decorateText method in order to decorate the text before 
   * returning the choosed place;
   */
  public String chooseAPlace() {
    Random rand = new Random();

    /**
     * All the proposed places are stored in proposedPlaces
     * global variable.
     * proposedPlaces is a list of elements, each element has 
     * a number that defines its position (0, 1, 2, 3) 
     * starting from 0.
     * To select a place from the list, we need to specify 
     * its position number.
     * To randomly select a number, we will use the "rand" 
     * object instance to access to a method called 
     * "nextInt()".
     * We need to tell the "nextInt()" what is the maximum 
     * number of options (if you set 4, the method will 
     * choose a number between 0 and 4).
     * The maximum number of options is the number of items
     * in our proposedPlaces list.
     * To get the number of items in proposedPlaces, we use
     * the size() method which returns an Integer number with
     * the count of items in the list.
     */
    int countOfPlaces = proposedPlaces.size();
    int randomPlacePosition = rand.nextInt(countOfPlaces);


    String choosedPlace = this
                          .proposedPlaces
                          .get(randomPlacePosition);

    String decoratedText = decoratedText(choosedPlace);

    return decoratedText;
  }

  private String decorateText(String textToDecorate){
    String decoratedText = "Hi! This is " + this.botName + ". The winner this week is: " + textToDecorate + ". Schedule this date to meet your friends: " + this.dayOfWeek + " " + this.hour;

    return decoratedText;
  }
}

We are done! Now, we can use our bot in this way:

// ✅ Create a bot instance and configure it
// Remember that the args we are passing through will be received by the constructor method
Bot ourSuperBot = new Bot("Mr Bot", "friday", "5:20pm");

// ✅ Execute the proposeAPlace method as many times you need
ourSuperBot.proposeAPlace("Beerhole"); // Peter propose "Beerhole"
ourSuperBot.proposeAPlace("Sam's Bar and Wine"); // Sara propose "Sam's Bar and Wine"
ourSuperBot.proposeAPlace("Super Taco"); // and you propose "Super Taco"

// ✅ Finally, we ask the ourSuperBot object to randomly choose 
// a place and store it in a new String type variable.
String choosedPlace = ourSuperBot.chooseAPlace();

If you try yo access to private members the Java will compiler stop you and throw an error:

// ❌ Will throw an error because decorateText is for internal class usage only (private)
ourSuperBot.decorateText("Empanadas Juanita");

// ❌ Will throw an error because proposedPlaces is for internal class usage only (private)
ourSuperBot.proposedPlaces;

Great! You can see this code in action thanks to replit.com which allows us to edit and run Java online. Click on the Green Button to re-run the code and see how the place changes randomly.

I hope this post was helpful for you. I know there are some redundant parts. I did so because repetition while learning helps me to remember. Sorry for that. If you have any question or feedback, feel free to leave a comment. I will read you as soon as possible to improve the post.

I'm writing it in Spanish too para la banda que habla español so when I finish I will update this post to add some illustrations. Thanks for reading!