Nombre del proyecto: Clean Code
Guía para implementar código fuente siguiendo estándares oficiales, como Microsoft o SOLID,
en los desarrollos de C# de las app´s de cualquier empresa.
Objetivo
El equipo IT de empresa comparte código fuente entre sus diferentes miembros. El objetivo del
presente documento es proporcionar guías para unificar la implementación del mismo en las
diferentes app´s de La empresa y así mejorar la vida diaria de los desarrolladores en el
mantenimiento del código fuente: resolución de bug´s, evolutivos, mejoras, etc… .
Introducción
Clean Code significa código limpio, código legible, código claro que se entiende, que es fácil de
leer y de interpretar, es un código que es fácil de extender y/o adaptarse a cambios.
Nace como repuesta a las malas costumbres en un sector presionado por preocupaciones
financieras sobre la responsabilidad del desarrollador, consiguiendo que en el sector sea
habitual desarrollar código que “funciona” antes que desarrollar código que funciona y que
además sea limpio, legible, extensible y bien estructurado. En definitiva, un código que puede
ser interpretado por humanos fácilmente y no solo por el compilador: “todo el mundo puede
implementar código que sepa leer un computador, pero no todo el mundo puede implementar
código que pueda leer un humano”.
Cuantas veces se ha oído “lo hago así porque no tengo tiempo”, se puede pensar que es como
decir “no hago bien mi trabajo porque no tengo tiempo, así que lo hago mal para tenerlo antes”.
Al final todo esto son herramientas y definiciones para ser un buen profesional del desarrollo de
software pero hay que saber aplicarlo con lógica y sentido común.
La belleza del código debe verse como herramienta, no como objetivo. No podemos
eternizarnos en corregir un bug urgente cuando seguramente no sea el mejor escenario para
andarse con sutilezas. Hay que ser inteligentes, existen momentos puntuales en los cuales una
chapuza (momentánea) puede solucionar un problema gordo y ahorrar mucho dinero a la
empresa (la cual nos paga). Cada solución tiene su contexto y es nuestra labor saber elegir la
mejor solución a realizar según las circunstancias.
El código limpio (clean code) no es algo recomendado o deseable, es algo vital para las
compañías y los programadores. La razón es que cada vez que alguien escribe código
enmarañado y sin pruebas unitarias (código no limpio), otros tantos programadores pierden
mucho tiempo intentando comprenderlo, invierten esfuerzo y crece el desánimo. Incluso el
propio creador de un código no limpio si lo lee a los seis meses será incapaz de comprenderlo y
por tanto de evolucionarlo.
1
Existe la regla del Boy Scout “Hay que dejar el código mejor de cómo lo encontraste”. Esto va en
la línea de la mejora continua y de la imposibilidad de hacerlo perfecto a la primera.
En la fase de refactorización es donde realmente aplicamos todos los aspectos vistos de código
limpio: aumentar cohesión, dividir clases, modularizar aspectos, elegir nombres adecuados… Es
imposible hacer un código limpio a la primera, así que es necesario refactorizar después de que
el código funcione, y es necesario hacerlo antes de pasar a la siguiente tarea.
DRY PRINCIPLE (Don´t Repeat Yourself)
Probablemente, el mayor enemigo del código limpio es el código duplicado. El código duplicado
hace que nuestro código sea más difícil de mantener y comprender, además de generar posibles
inconsistencias. Hay que evitar el código duplicado siempre. Para ello, dependiendo del caso
concreto, la refactorización, la abstracción o el uso de patrones de diseño de diseño pueden ser
nuestros mejores aliados.
Utiliza método o funciones, encapsulamiento de código con una sola responsabilidad. Puedes
hacer parametrizable. Pon un nombre descriptivo a esa función con el cual, con tan solo leer su
nombre, se sabe lo que va a hacer.
THE PRINCIPLE of LEAST SURPRISE
Las funciones, métodos o clases deben hacer lo que (razonablemente) se espera de ellas. Es
decir, una función o una clase debe tener, en función de su nombre, un comportamiento obvio
para cualquier programador, sin que este tenga la necesidad de sumergirse en su código....
ExcelUtil: se entiende que es una clase con métodos para trabajar con el formato de
ficheros Excel; ejemplos: dar un xlsx a partir de una tabla, devolver una tabla a partir
de un xlsx, transformar un xlsx a csv, etc…
EmailUtil: envío de email´s
ZipUtil: se entiende que es una clase con métodos para trabajar con el formato de
ficheros Zip; comprimir un zip, extraer un zip, etc..
Single Responsibility Principle
2
El principio de Responsabilidad Única (la S de los principios SOLID), hace referencia al diseño de
nuestras clases. Dice que: «una clase debe tener una y solo una razón para cambiar». Debe tener
una única responsabilidad, solo debe hacer una cosa (la que indica su propio nombre).
Nombres con sentido
El desarrollador a lo largo de su vida profesional lee más código que el que escribe. Por ello
debemos poner especial interés en escribir correctamente. Un buen nombre da mucha más
información que cualquier otra cosa, debemos elegirlo bien, sabiamente y no decidirlo a la
ligera.
Todos los nombres (métodos, clases, etc…) deben ser intencionados, claros y descriptivos.
Evitar abreviaciones, siglas, acrónimos, uso secuencias de números en variables. Ejemplos
incorrectos:
var n = “Pedro” //Nombre
var n = “Pedro”
var n1= “Juan”
var n2 = “Jacob”
var nom = “Pedro”
var fn; //FechaNacimiento
var usuRepo // usuarioRepositorio
Usar siempre las mismas palabras para lo mismo.
Los nombres cuanto más cortos mejor, siempre que sean explícitos y claros.
Funciones
Deben ser reducidas y con nombre descriptivos. Solo deben hacer una cosa.
Intentar evitar los parámetros de salida (out o ref): son confusos, mejor funciones que retornen
valor.
Funciones sin efectos secundarios, que hagan lo que dice su nombre y nada más oculto.
Mejor devolver excepciones que códigos de error siempre. En general no es recomendable
devolver null, en su lugar es mejor devolver una excepción o un objeto de caso especial.
Comentarios
3
Los comentarios solo están justificados cuando no somos capaces de expresarnos con el código.
En general, basta con escribir y encapsular en una función que se llame como lo que hay en el
comentario.
Comentarios incorrectos:
Que dejan dudas en la explicación.
Redundantes.
Registro de cambios (para ello está el control de código fuente)
Código comentado y comentarios sobre cosas que no están en el código adyacente.
Solo algunos comentarios son positivos:
Comentarios legales, de derechos de autor.
El summary; y prácticamente obligatorio.
Explicación de la intención, decisión tomada o advertencia.
Comentarios TODO.
Formato
El tamaño de los ficheros debe ser coherente; si no, separar en clases.
Las variables de un método/función se deben declarar lo más cerca posible a su uso.
No deberíamos hacer scroll horizontal para leer código.
No usar más de un espacio en blanco entre las líneas (parcelas).
Indentar el código.
El código es compartido, y leyéndolo no deberíamos ser capaces de identificar a su autor.
Clases
Orden dentro de la clase: contantes, variables estáticas, variables de instancia, constructor,
propiedades y funciones/métodos públicos, protegidos y privados.
El tamaño debe ser reducido y debe tener una única responsabilidad: la que indica su nombre.
Cuando organizamos la complejidad del software, es mejor organizarla en cajones pequeños
bien etiquetados que no en cajones de sastre enormes.
El código muerto, bien que no se ejecuta nunca o bien que está comentado directamente, se
elimina: existe source control. Esto también aplica a variables/propiedades sin usar. Incluyendo
using´s sin usar o dll´s del proyecto.
Sustituir números mágicos por constantes con nombres correctos, también aplica a string´s.
Los campos son privados, las propiedades públicas.
4
Sintaxis
- Nomenclatura CamelCase:
public class ActividadCliente
public void BorrarEstadisticas()
public void CalcularEstadisticas()
public void Add(Elemento item)
HtmlHelper htmlHelper;
FtpTransfer ftpTransfer;
UIControl uiControl;
public class Account
public string Number {get;set;}
public DateTime DateClosed{get;set;}
public const decimal NUMERO_MAXIMO_ROWS;
- Se debe usar los alias de los tipos predefinidos:
Incorrectos:
String name
Int32 index
Boolean isSaved
Correctos:
string name
int index
boolean isSaved
- Se debe usar el tipo implícito var solo si en la parte derecha de la asignación queda claro
el tipo:
Incorrectos:
var stream = [Link](path);
int index = 100;
Correctos:
var index = 100;
var user = new User();
- El nombre de los archivos de código fuente debe coincidir con la clase. Y debe
haber uno por cada clase/interfaz/enum. No es lógico/sano meter en un fichero
todo el proyecto (cajón de sastre).
// Archivo [Link]
5
public partial class Task
- Evitar usar abreviaciones excepto las abreviaturas comúnmente utilizadas: Id,
XML, FTP, Uri…
Incorrectos:
UserGroup usrGrp
Correctos:
UserGroup userGroup
- Se debe usar el inicializador de objectos
Incorrectos:
Cat cat = new Cat();
[Link] = 10;
[Link] = "Fluffy";
Correctos:
var cat = new Cat { Age = 10, Name = "Fluffy" };
- Los campos de una clase empiezan en minúscula y sus propiedades/métodos/funciones
en mayúscula. Sus constantes todo en mayúsculas (separación de palabras con _). Los
argumentos de un método/función en minúscula.
private int age;
public int Age { get; set;}
private const int MAX_AGE_ALLOW = 65;
- Para referenciar a las diferentes instancias de la clase dentro de ella misma usamos
this, base si está en la herencia.
public void SetAge(int age){
[Link] = age;
}
- Existen nombres de variables estandarizados:
o El nombre de la variable devuelto por un método siempre se llama result.
o El nombre del parámetro de una función el cual se va a formatear/tratar y es
devuelto tras su procesamiento se llama source.
- Los using´s dentro del namespace. Y borrar de ellos las partes innecesarias.
- Usar siempre que se pueda la cláusula using antes que close y/o dispose.
- Usar [Link] y no “”.
- Para concatenar cadenas usar el carácter de escape $ y no +
6
var fullName = $"{name} {firstName} {lastName}";
- Los nombres de los campos/propiedades/métodos de tipo bool o que devuelven bool
deben contestar sí o no a una pregunta (la pregunta es el nombre de la variable); ya que
devuelven verdadero o falso. Generalmente las prefijamos con Is o Has (es…? tiene…?)
Incorrectos:
bool ok;
public bool Validate()
bool car;
Correctos:
bool isOk;
public bool IsValidate()
bool hasCar;
- Usar los métodos de la clase string para comprobaciones de nulo y vació:
[Link] o [Link].
Incorrectos:
if (field03 != "" && field03 != null)
Correctos:
if!([Link] (field03))
- Usar los if ternarios.
Incorrecto:
if (field03 != "" && field03 != null)
{
this.D_Concepto_impuesto =
[Link]().ToUpper();
}
else
{
this.D_Concepto_impuesto = "";
}
Correcto:
this.D_Concepto_impuesto = [Link](field03)
? [Link]().ToUpper()
: [Link];
7
Arquitectura
La arquitectura de una aplicación es sumamente importante: rendimiento, mantenibilidad,
coste, etc…
Existen muchas: 3 capas, DDD, CQRS, etc…
La más elemental y recomendada para aplicaciones “sencillas” es 3 capas.
Consiste en separar la interfaz gráfica (ui), la capa de negocio (bll) y la capa de acceso a datos
(dal). Las aplicaciones de La empresa por lo general deben usar esta arquitectura.
Al implementar este modelo de programación, se asegura un trabajo de forma ordenada y
separada, debido a que sigue el principio de “divide y vencerás”
Cada capa está dividida según su funcionalidad y cuando se quiere modificar el sistema basta
con cambiar un objeto o conjunto de objetos de una capa. Esto se llama modularidad.
Independencia. No es lógico/sano meter en un proyecto todo la app (cajón de sastre)
Es más fácil la detección de errores y por tanto su resolución. Es más fácil los cambios.
