Some best practices for software development

best_practices.md

Index

1. Avoid comments when possible; they are unnecessary and may potentially lie.
2. Use clear method (and variable) names, as long as necessary.
3. Break down long methods
5. Avoid secondary effects when possible; they obfuscate the code.
6. Use constants/enums instead of literals; they help maintainability.

Other stuff

1. Build Strings with String.format
2. Avoid NPEs when method-chaining
3. []

---

Avoid comments when possible

Avoid comments when possible: they are unnecessary if we use clear method and variable names, and encapsulate methods. They can even potentially lie, if the underlying implementation changes.

Evitar comentarios cuando sea posible; son innecesarios si usamos nombres claros para los métodos y variables, y encapsulamos los métodos. Pueden incluso llegar a mentir, si la implementación a la que acompañan cambia.

Clear method (and variable) names

Use clear method names and variable names that make the intention of the code clear (ex. sortedEvents). It's preferrable to use longer names than to add a comment.

Usar nombres claros para las variables y los métodos, que muestren la intención del código de manera clara. Es preferible usar nombres más largos antes que añadir un comentario.

Avoid secondary effects when possible

Avoid secondary effects when possible. Given a method call, any programmer must understand its consequences, so the author must try to avoid modifying global/class/instance variables in a manner that is not clear by the method name.

Evitar efectos secundarios cuando sea posible. Dada una llamada a un método, todos los programadores deben entender sus consecuencias, con lo que el autor debe evitar modificar variables globales/de clase/de instancia de una forma que no sea clara por el nombre.

Use constants/enums instead of literals

Using constants/enums has two advantages over literals:

1. Avoids naming mistakes (ex. "tankcontainer" vs "tank_container") thanks to IDE autocompletion.
2. Helps to trace usage. You can show uses of a constant using the IDE, but can you only do a raw text search for literals.

Utilizar constantes/enumerados en vez de literales tiene dos ventajas:

1. Evita errores de nombrado (ej. "tankcontainer" vs "tank_container") gracias al autocompletado del IDE.
2. Permite trazar el uso. Podemos mostrar los usos de una constante con el IDE, pero con los literales solo podemos hacer una búsqueda de texto.

---

Build Strings with String.format

• String str = "Hello world: " + obj (concatenation) will throw a NPE if any argument is null.

• String str = String.format("Hello world: %s", obj) will not throw a NPE. Use whenever possible.

• String str = "Hello world: " + obj (concatenation) lanzará un NullPointerException si cualquier argumento es null.

• String str = String.format("Hello world: %s", obj) no lanzará un NullPointerException. Usarlo cuando sea posible.

Avoid NPEs when method-chaining

When "method-chaining" (ex. userBean.getId().longValue()) we must control the possibility that any of the returns might be a null (ex. userBean.getId() != null ? userBean.getId() : null).

Cuando encadenamos métodos (ej. userBean.getId().longValue()) debemos controlar la posibilidad de que cualquiera de los valores retornados pueda ser null (ej. userBean.getId() != null ? userBean.getId() : null).

Use try/catch in I/O operations

I/O operations are usually delicate and we should prepare for the worst case and handle it with a try/catch block.

Las operaciones I/O suelen ser delicadas y debemos considerar el peor caso utilizando un bloque try/catch.

To do: add citations, correct headers/index, maybe separate translation