best-practices

Este es un documento vivo sobre convenciones y prácticas que recomendamos seguir a lo largo del curso de Desarrollo Web Full Stack.

Sugerencias

Si tienes alguda duda, comentario o sugerencia (bienvenida!), puedes abrir un issue.

Comparte

Si te resultó útil, te agradecemos que lo compartas. También puedes seguirnos en Twitter ó Instagram 💪

Contenido

• Disclaimer
• General
• HTML5
• CSS3
• Git
• Comentarios
• JavaScript

Disclaimer

Las buenas prácticas son convenciones que adoptamos para estandarizar nuestra forma de desarrollar, utilizar ciertos patrones que nos permitan evitar algunos errores comunes y escribir código de mayor calidad, legible, mantenible, escalable, etc.

• No son reglas. Siempre debemos tener en cuenta el contexto y no aplicarlas ciegamente.
• Son subjetivas y muchas veces arbitrarias.

Esta es sólo una guía general que toma ciertas prácticas comunes. Resulta fundamental por eso, seguir las guías de buenas prácticas y estilos del proyecto en el que estemos trabajando y si no las tuviese, buscar la oportunidad de discutirlas y definirlas.

General

• Para nombrar archivos y carpetas, utilizar lowercase (minúsculas), separando palabras con guiones medios. Ej: index.html, common-styles.css.
• Usar soft tabs (2 espacios) para indentar el código.
• LCS: para cualquier código que escribamos, intentar, en lo posible, optimizarlo para que sea
  • Legible
  • Consistente
  • Simple
• Nunca olvidarnos de que escribimos código para otras personas. Debería ser simple de entender. Como diría el gran Kyle Simpson, Code is for Humans. Salvo que estemos programando compiladores, claro.
• Utilizar styleguides para estandarizar y normalizar la forma en que escribimos código. Ejemplos: Mark Otto - HTML & CSS Styleguide, AirBnB - CSS Styleguide, AirBnB - JavaScript Styleguide.
• Utilizar herramientas tales como linters y formateadores de código. Esta es una guía para realizar el setup de Eslint + Prettier. Existen alternativas similares, lo importante es fijar alguna convención y styleguide para el proyecto.

HTML5

• Definir/planificar la estructura de nuestro sitio en secciones o componentes, antes de empezar a escribir el código. Lápiz y papel!
• Separar el contenido/estructura de la presentación. Para los estilos usamos CSS, evitar tags como bó i por ejemplo.
• Usar HTML5 y tags semánticos. No abusar del div.
• Usar los distintos tipos de headings cuando corresponda (h1...h6), para darle jerarquía al contenido de nuestro sitio y facilitarle el trabajo a screen-readers y buscadores.
• Evitar, en lo posible, los contenedores genéricos. No abusar del div.
• Siempre declarar el DOCTYPE.
• Agregarle al tag htmlel atributo lang, con el valor correspondiente.
• Siempre agregarle el atributo alt a las imágenes, con un texto descriptivo.
• Indentar nuestro código apropiadamente en el editor, para escribir código más legible, facilitar la colaboración y el trabajo en equipo.

CSS3

• Estilar, en lo posible, usando clases. De esta forma obtenemos mayor control sobre la especificidad y resulta más fácil componer estilos.
• Para los nombres de las clases utilizar lowercase (minúsculas), separando palabras con guiones medios. Ej: .custom-btn.
• Evitar utilizar selectores de ID. Introducen un alto nivel de especificidad a nuestras reglas y no son reutilizables.
• Evitar, en lo posible, utilizar estilos inline e !important para no alterar la especificidad y dificultar el mantenimiento posterior.
• Si utilizamos selectores múltiples para definir una regla de estilo, escribir cada uno en su propia línea.
• Separar cada regla de estilo con 1 línea en blanco.
• Si usamos HTML5, con tags más semánticos y no genéricos, vamos a escribir menos CSS, más legible y mantenible.
• Reutilizar estilos comunes entre componentes, utilizando la cascada.
• Componer estilos usando clases (ver, por ejemplo, cómo aplica esto Tachyons).
• Reset: utilizar box-sizing: border-box para todos los elementos del sitio, al igual que empezar con margin y padding en 0.
• Es recomendable escribir los selectores más genéricos al principio para evitar pisar estilos.
• En lo posible, definir alguna convención para el nombre de los selectores y tratar de mantenerla. Ser consistentes.

❌ Mmm, mejor no

.avatar{
    border-radius:50%;
    border:2px solid white; }
.no, .nope, .not_good {
    // ...
}
#lol-no {
  // ...
}

✅ Ok

.avatar {
  border-radius: 50%;
  border: 2px solid white;
}

.one,
.selector,
.per-line {
  // ...
}

Git

• Escribir mensajes de commits en inglés.
• Escribir mensajes de commits descriptivos.
• En lo posible, comitear de forma frecuente.
• Intentar, en lo posible, realizar commits atómicos.
• Escribir los mensajes de commits en tiempo presente, modo imperativo.
• Más tips para escribir mejores mensajes de commit acá.
• Eliminar los branches que ya no utilizamos, tanto localmente como de GitHub.
• Antes de hacer un pull para traernos los cambios nuevos, hacer commit de nuestros cambios locales

Comentarios

• Utilizar, en lo posible, comentarios minimales, es decir, los necesarios, ni más ni menos. Para ver mejor de qué se trata esto, leer la sección Minimal Comments del artículo The Exceptional Beauty of Doom 3's Source Code.
• Los comentarios deberían hablarnos , en lo posible, del por qué, no del qué. El por qué implica darle información sobre el contexto del problema y las decisiones que tomamos a nuestros lectores, que para nosotros es evidente pero no para el resto. El código debería ser lo suficientemente claro para describir el qué.
• Si nuestro código está demasiado comentado, podemos tomarlo como indicador de que quizás no sea lo suficientemente claro.

JavaScript

• El código que escribimos no es para la máquina, sino para comunicar ideas a otras personas. Por eso, queremos que sea lo más claro posible. Ver Code is for Humans y Don’t be clever.
• Utilizar nombres descriptivos para constantes, variables y funciones. Ver ítem anterior.
• En lo posible, escribir 1 instrucción por línea de código.
• Utilizar const por defecto.
• Si queremos definir algo explícitamente como variable, utilizar let.
• Evitar usar var.
• Utilizar igualdad/desigualdad estricta para las comparaciones, para evitar caer en las trampas del type coercion.
• Utilizar, en lo posible, funciones puras en nuestro código.
• Utilizar los métodos de Array para operaciones que hagamos con los mismos.
• Evitar el uso de variables globales.