Manual de Clean Code

 

 

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 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  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 so n herramientas y definiciones para ser un buen pro profesional fesional 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, ele gir nombres adecuados… Es imposible hacer un código limpio li mpio 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 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  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 pro piedades públicas. 4

 

 

Sintaxis - 

Nomenclatura CamelCase:           

- 

                     

 public cla class ss ActividadCliente ActividadCliente   public voi void d BorrarEstadisticas() BorrarEstadisticas()   public void CalcularEstadisticas() )  void CalcularEstadisticas( void Add(Elemento  public void Add(Elemento item) 

HtmlHelper htmlHelper;  FtpTransfer ftpTransfer;  UIControl uiControl;  class ss Account   public cla string ing Number {get;set;}   public str DateTime DateClosed{get;s  public DateTime DateClosed{get;set;} et;}  const decimal NUMERO_MAXI  public const NUMERO_MAXIMO_ROWS; MO_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  solo si en la parte derecha de la asignación queda claro el tipo:

Incorrectos:  

   

var stream = File.Create(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 Task.cs

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(); cat.Age = 10; cat.Name = "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){ this.Age = 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 clá usula using antes que close y/o dispose.

- 

Usar string.Empty  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. falso. Generalmente las prefija prefijamos mos 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ó: string.IsNullOrEmpty o string.IsNullOrWhiteSpace.

Incorrectos: 

 

if (field03 != "" && field03 != null)

Correctos: 

- 

 

if!(string.IsNullOrEmpty (field03))

Usar los if ternarios.

Incorrecto: if (field03 != "" && field03 != null) {

this.D_Concepto_impuesto field03.Trim().ToUpper(); } else { this.D_Concepto_impuesto = ""; }

Correcto: this.D_Concepto_impuesto = string.IsNullOrEmpty(field03) ?

field03.Trim().ToUpper()

: string.Empty; string.Empty;

7

=

 

 

Arquitectura La arquitectura de una aplicación es sumamente importante: importante:  rendimiento, mantenibilidad, coste, etc…  Existen muchas: 3 capas, DDD, CQRS, etc…  La más elemental y recomendada para aplicaciones aplicac iones “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.

8