Introduccin ......................................................................................................................... 2 Propsito de definir estndares de codificacin y mejores prcticas ....................................

2 Cmo controlar el uso del estndar propuesto en el equipo de trabajo ................................ 3 Convencin de nombres y estndares ................................................................................. 3 Las reglas de nomenclatura para el cdigo son las siguientes: ............................................ 4 Notacin general:.......................................................................................................... 5 Identacin y espacios ................................................................................................... 7 Buenas prcticas de programacin ............................................................................. 10 Arquitectura ....................................................................................................................... 15 ASP.NET ........................................................................................................................... 16 Comentarios ...................................................................................................................... 16 Uso de Excepciones .......................................................................................................... 17 Bibliografa ......................................................................................................................... 19

Estndar de codificacin para C# y buenas prcticas de programacin

Introduccin
Cualquier persona puede escribir cdigo. Con unos pocos meses programando, cualquier persona puede escribir aplicaciones que corren. Hacer funcionar una aplicacin es relativamente sencillo, pero escribirla correctamente requiere de un mayor esfuerzo y conocimiento.

Escribir cdigo de calidad es un arte y el objetivo de este documento es dar los lineamientos para ser exitosos en esa tarea.

Existen diferentes definiciones de lo que es un buen cdigo. Sin embargo, y para no entrar en discusiones tericas, para todo efecto, las pautas bsicas que se deben guiar la escritura de cdigo son las siguientes:

El cdigo debe ser fcilmente legible La forma en que est escrito el cdigo debe facilitar su mantenimiento El cdigo debe ser eficiente en todo sentido

Propsito de definir estndares de codificacin y mejores prcticas

Para desarrollar aplicaciones confiables y escalables, se deben seguir estndares de programacin y buenas prcticas

La convencin de nombres, los estndares de codificacin y las buenas prcticas descritos en este documento son un compilado de las guas de Microsoft, as como de otros trabajos y de la experiencia de los autores del documento.

Existen muchos estndares en la industria de la programacin. Ninguno de ellos es bueno o malo, el criterio de seleccin del estndar o de la aproximacin adecuada depende de las necesidades y de la naturaleza de los proyectos que se necesitan desarrollar.

Este documento pretende definir un estndar conveniente para el desarrollo del proyecto ADO, de acuerdo a la arquitectura propuesta y los lenguajes de programacin seleccionados.

Cmo controlar el uso del estndar propuesto en el equipo de trabajo

Dado que los equipos de trabajo para los proyectos estn conformados por diferentes roles y niveles de experticia, el primer paso para adoptar el estndar debe ser lograr el consenso de todas las personas involucradas, en cuanto a la pertinencia de las definiciones establecidas y el compromiso para trabajar con ellas.

La mejor aproximacin para lograr esto es realizar una reunin de grupo para oficializar el documento. En esta reunin se deben discutir los diferentes puntos de vista y se debe lograr la concertacin acerca de si todas las guas propuestas son vlidas o si por el contrario se deben excluir ciertas pautas del documento o aadir algunas otras que hagan falta. Esta discusin debe ser convocada y guiada por el lder tcnico o el gerente del proyecto.

Despus de tener la versin oficial del documento y de iniciar el desarrollo, se deben incluir dentro del cronograma del proyecto, actividades puntuales para realizar las revisiones de cdigo. Se recomiendan 3 tipos de revisiones:

1.

2.

3.

Revisin de pares otro miembro del equipo revisa el cdigo para asegurar que se estn siguiendo los estndares. Este nivel de revisin puede tambin incluir algunas pruebas unitarias. Cada archivo en de la solucin debe pasar por este proceso. Revisin del arquitecto El arquitecto debe revisar los mdulos principales de cada proyecto para asegurar que estn acordes con el diseo propuesto y que no existe ningn error grave que pueda afectarlo. Revisiones grupales aleatoriamente se debe seleccionar uno ms archivos para realizar una revisin grupal de los mismos (se sugiere que esto se realice una vez por semana). Se debe distribuir una copia impresa de los archivos una hora antes de la reunin. El grupo debe revisar el material y llegar a la reunin con las observaciones o los puntos para la discusin. En la reunin se debe explorar cada seccin del cdigo y se le debe permitir a cada miembro del grupo dar sus observaciones o sugerencias acerca de cmo esa pieza de cdigo podra ser escrita de una mejor manera (se debe tener en cuenta resaltar el buen trabajo de los desarrolladores y tambin asegurarse de no ofender ni reprochar a nadie en las discusiones).

Convencin de nombres y estndares

Nota : Los trminos notacin Pascal y notacin Camel son usados a lo largo de este documento. Notacin Pascal La primera letra de todas las palabras debe ir en mayscula y los otros en minscula. Ejemplo: BackColor Notacin Camel El primer caracter de todas las palabras, excepto el de la primera palabra deben ir en mayscula y las otras en minscula. Ejemplo: backColor

Las reglas de nomenclatura para el cdigo son las siguientes:

1. Todos los nombres de clases, variables, constantes, parmetros y dems identificadores se deben escribir en idioma Ingls.

2.

Uso de notacin Pascal para nombres de clases

public class HelloWorld { ... }

3.

Uso de notacin Pascal para nombres de mtodos

void SayHello(string name) { ... }

4.

Uso de notacin Pascal para nombres de variables miembro de clase

Propiedades:

DateTime InsertDate { get; set; }

Variables miembro de clase que no se exponen:

private String _FirstName

5.

Uso de notacin Camel para variables y parmetros de mtodos

int totalCount = 0; void SayHello(string lastName) { string fullMessage = "Hello " + name; ... }

6.

Uso de notacin Pascal en las enumeraciones (tanto en la definicin como en sus miembros):
public enum DBActionEnum { Save, Delete }

Las enumeraciones que tengan alcance global (que sean definiciones que apliquen a la lgica de ms de una clase deben colocarse en un archivo .cs separado.

Las enumeraciones que solo aplican para un clase puntual, se deben colocar dentro de la misma clase.

7.

Uso del prefijo I con notacin Pascal para interfaces ( Ejemplo: IEntity )

Notacin general:
8.

Emplee nombres de variables significativos y auto-descriptivos. No utilice abreviaciones:

Permitido:

string address int salary

No permitido:

string nam string addr int sal

9.

Por ningn motivo se permite el uso de caracteres simples para nombres de variables, tales como: i, n, s etc. En caso de requerir ndices o variables temporales/auxiliares en aserciones de control use nombres como: index, temp

La nica excepcin permitida a esta regla es en las estructuras para ciclos como el for:

for ( int i = 0; i < count; i++ ) { ... }

10. Por ningn motivo use underscores (_) para nombres de variables dentro de mtodos.

11. Todas las variables miembro de clase que no se expongan como propiedades deben ir con el prefijo underscore (_) para que estas puedan ser identificadas o diferenciadas de las otras variables local (Ejemplo: private String _FirstName). 12. Emplee la notacin abreviada del framework 2.0 y superiores para definir propiedades Ejemplo:

DateTime InsertDate { get; set; } int InsertENTUserAccountId { get; set; }

13. Las variables boolean deben ir con el prefijo is (Ejemplo: private bool _isFinished).

14. Los espaciones de nombres o namespaces deben serguir el siguiente estndar:

<nombre de la unidad Amadeus>.<nombre del producto>.<mdulo principal>.<mdulo secundario>
Ejemplo:

AmadeusLATAM.ADO.BoletotalDispatcher 15. Use un prefijo adecuado para los elementos del la capa de usuario UI para que las variables de esta capa puedan ser fcilmente identificables.

a.

Usar el prefijo correspondiente para cada elemento de la capa de UI. A continuacin se presenta una lista resumida:

Tipo de Control Label TextBox DataGrid Button ImageButton Hyperlink DropDownList

Prefijo para el nombre lbl txt dtg btn imb hlk ddl

ListBox DataList Repeater Checkbox CheckBoxList RadioButton RadioButtonList Image Panel PlaceHolder Table Validators

lst dtl rep chk cbl rdo rbl img pnl phd tbl val

16. El nombre del archivo debe coincidir con el nombre de la clase (Ejemplo: para la clase HelloWorld,

el nombre del archivo correspondiente debe ser HelloWorld.cs)

Identacin y espacios
1. Use tabulaciones para identar el cdigo. Por ningn motivo use ESPACIOS. Defina el tamao de la tabulacin como 4 espacios.

2.

Los comentarios deben estar al mismo nivel del cdigo (use el mismo nivel de identacin).

Forma correcta:

// Format a message and display string fullMessage = "Hello " + name; DateTime currentTime = DateTime.Now; string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString(); MessageBox.Show ( message );

Forma incorrecta:

// Format a message and display string fullMessage = "Hello " + name; DateTime currentTime = DateTime.Now; string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString(); MessageBox.Show ( message );

3.

Las llaves ( {} ) del cdigo que las genera. El cdigo dentro de ellas debe ir identado tal como se muestra:

4.

Use un interlineado para separar bloques de cdigo:

Forma correcta:

bool SayHello ( string name ) { string fullMessage = "Hello " + name; DateTime currentTime = DateTime.Now; string message = fullMessage; MessageBox.Show ( message ); if ( ... ) { // Do something // ... return false; } return true; }

Forma incorrecta:

bool SayHello (string name) { string fullMessage = "Hello " + name; DateTime currentTime = DateTime.Now; string message = fullMessage; MessageBox.Show ( message ); if ( ... ) { // Do something // ... return false; } return true; }

5.

Debe haber una y solo una lnea en blanco de separacin entra cada mtodo dentro de la clase.

6.

Los parntesis deben ir en separados a un espacio de las instrucciones if, for etc. y la llave que
abre el bloque de cdigo debe ir en la siguiente lnea:

Forma correcta:

if ( ... ) { // Do something }

Forma incorrecta:

if( ... ) { // Do something }

7.

Coloque un espacio en blanco antes y despus de cada sentencia dentro de los if, for etc.
Forma correcta:

if ( showResult == true ) { for ( int i = 0; i < 10; i++ ) { // } }

Forma incorrecta:

if(showResult==true) { for(int { // } }

i= 0;i<10;i++)

8.

Use regions #region para agrupar bloques de cdigo relacionados:

9.

Mantenga privadas las variables que son miembro de clase.

10. Las variables de clase, propiedades y mtodos deben ir en la parte superior de la clase, los miembros deben ir en la parte inferior. 11. Evite crear en lo posible ms de una clase en un mismo archivo fsico. 12. Haga un manejo adecuado de las clases y mtodos parciales.

Buenas prcticas de programacin

1. Evite escribir mtodos de ms de 50 lneas de cdigo. Un mtodo debe tener entre 1 y 25 lneas de cdigo. Si el mtodo tiene ms de 50 lneas considere la posibilidad de separar la lgica en ms mtodos.

2.

El nombre de los mtodos debe ser auto-descriptivo (debe significar su propsito). No utilice nombres que no tengan significado. Si el nombre del mtodo es obvio y totalmente explicativo, no es necesario que se haga documentacin acerca de lo que hace el mtodo.
Forma correcta:

public void SavePhoneNumber ( string phoneNumber ) { // Save the phone number. }

Forma incorrecta:

// This method will save the phone number. public void SaveDetails ( string phoneNumber ) { // Save the phone number. }

3.

Un mtodo debe tener un solo propsito. No combine ms de un propsito o ms de una tarea en un solo mtodo, an si esas tareas son bastante similares

Forma correcta:

// Save the address. SaveAddress ( address ); // Send an email to the supervisor to inform that the address is updated. SendEmail ( address, email ); public void SaveAddress ( string address ) { // Save the address. // ... } public void SendEmail ( string address, string email ) { // Send an email to inform the supervisor that the address is changed. // ... }

Forma incorrecta:

// Save address and send an email to the supervisor to inform that // the address is updated. SaveAddress ( address, email ); public void SaveAddress ( string address, string email ) { // Job 1. // Save the address. // ... // Job 2. // Send an email to inform the supervisor that the address is changed. // ... }

4.

Use en lo posible los tipos bsicos especficos de C#, en vez de utilizar los tipos complejos definidos en el espacio de nombres System. Los tipos complejos, aunque tienen mtodos que facilitan ciertas cosas, son estructuras ms pesadas para la mquina virtual.
int age; //(en lugar de Int16) string name; //(en lugar de String) object contactInfo; //(en lugar de Object)

5. Siempre tenga en cuenta valores inesperados. Por ejemplo, si est usando un parmetro que tiene dos posibles valores, nunca asuma que si uno de los valores no es el actual, entonces el segundo valor es el que aplica.

Forma correcta:

if ( memberType == eMemberTypes.Registered ) { // Registered user do something } else if ( memberType == eMemberTypes.Guest ) { // Guest user... do something } else { // Un expected user type. Throw an exception throw new Exception (Un expected value + memberType.ToString()); // If we introduce a new user type in future, we can easily find // the problem here. }

Forma incorrecta:

if ( memberType == eMemberTypes.Registered ) { // Registered user do something } else { // Guest user... do something // If we introduce another user type in future, this code will // fail and will not be noticed. }

6.

Nunca queme dentro del cdigo cadenas ni nmeros que pueda manejar como constantes o recursos dentro de un archivo de configuracin.

Sin embargo, el uso de constantes no es recomendado. En lugar de esto use contantes dentro del archivo de configuracin (.config) o en la base de datos.

7.

Use String.Empty en lugar de

Forma correcta:

if ( name == String.Empty ) { // do something }

Forma incorrecta:

if ( name == ) { // do something }

8.

Use enum cada vez que se requiera. No use nmeros o cadenas para indicar valores discretos dentro de sentencias switch: Forma correcta:
enum MailType { Html, PlainText, Attachment } public void SendMail (string message, MailType mailType) { switch ( mailType ) { case MailType.Html: // Do something break; case MailType.PlainText: // Do something break; case MailType.Attachment: // Do something break; default: // Do something break; } }

Forma incorrecta:

public void SendMail (string message, string mailType) { switch ( mailType ) { case "Html":

// Do something break; case "PlainText": // Do something break; case "Attachment": // Do something break; default: // Do something break; } }

9.

Nunca queme las rutas de archivos en cdigo. Obtenga programticamente la ruta y use rutas relativas.

10. Nunca asuma que el cdigo corre siempre desde la unidad C: 11. Evite usar sentencias foreach puesto que son bastante costosas a nivel de procesamiento.

12. Evite usar excepciones a menos que sea estrictamente necesario, en lugar de esto utilice valores

para tabular los tipos de errores.

13. Evite pasar ms de 5 parmetros en un mtodo. En caso de que se supere ese nmero de

parmetros, se debe contemplar la posibilidad de crear una estructura para encapsular esos parmetros.
14. Utilice los archivos AssemblyInfo para colocar informacin como el nmero de versin,

descripcin, nombre de la compaa, derechos de autor, etc.

15. Utilice no ms de 2 niveles de jerarqua de carpetas para organizar los archivos dentro de un

proyecto. 17. Si se abre una conexin a una base de datos, socket, file stream etc, siempre debemos asegurarnos de cerrarlas, por ejemplo, dentro del bloque finally o utilizar using.

18. Declare las variables tan cerca como sea posible del cdigo que las usa. No declare ms de una variable por lnea. 19. Use StringBuilder en vez de String cuando tenga que manipular objetos de tipo string en un ciclo. El objeto String trabaja en una forma ineficiente en estos casos en .Net: cada vez que se hace una concatenacin de un string, el framework descarta el objeto string anterior y recrea un nuevo objeto, lo cual es relativamente pesado a nivel de procesamiento. Considere el siguiente caso:

public string ComposeMessage (string[] lines) { string message = String.Empty; for (int i = 0; i < lines.Length; i++)

{ message += lines [i]; } return message; }

En el ejemplo de arriba, el cdigo muestra una concatenacin de un objeto string de nombre message. Pero esto no es lo que sucede en realidad, el objeto string es desechado en cada iteracin y recreado con la nueva lnea que se le est agregando.

Si el ciclo tiene varias iteraciones, es mejor utilizar un objeto StringBuilder en vez de un objeto String.

En el siguiente ejemplo se reemplaza el objeto String por un objeto StringBuilder

public string ComposeMessage (string[] lines) { StringBuilder message = new StringBuilder(); for (int i = 0; i < lines.Length; i++) { message.Append( lines[i] ); } return message.ToString(); }

Arquitectura
1. Siempre utilice una arquitectura multicapa (N-Tier).

2. Nuca debe accederse directamente a la base de datos desde las pginas de la capa UI. Siempre debe existir una capa de acceso a base de datos que realice todas las tareas relacionadas con esta. Esto ayuda o facilita la migracin a otra base de datos. 3. Use try-catch en la capa de acceso a datos para capturar todas las excepciones provenientes de la base de datos. Es decir, debe existir un manejador de excepciones cuyo propsito es el de registrar todas las excepciones que provienen de la base de datos. Los datos que deben quedar registrados deben incluir el nombre del comando que caus la excepcin (el comando ejecutado sobre la base de datos), el nombre del procedimiento almacenado que caus la excepcin, los parmetros (valores), cadena de conexin usada, etc. Despus de registrar la excepcin, esta deber ser manejada o propagada para las otras capas de la aplicacin, para que estas puedan hacer el manejo respectivo. (MAL REDACTADO, CORREGIR)

4. Separe la aplicacin en mltiples assemblies. Agrupe todas las clases utilitarias en una librera de clases separadas: se recomienda que todos los archivos relacionados con la base de datos vayan en una librera de clases separada.

ASP.NET
1. Evite el uso de variables de sesin en el cdigo .aspx. En vez de esto, use variables de sesin dentro de las clases (code behind) y exponga mtodos para acceder a esos valores almacenados. Una clase puede acceder las variables de sesin a travs del objeto System.Web.HttpCOntext.Current.Session.

2.

No almacene objetos grandes en sesin. Esto puede consumir una gran cantidad de memoria del servidor, dependiendo del nmero de usuarios conectados al Sitio Web. (APLICA PARA EL VIEWSTATE)

3.

Siempre use hojas de estilo para controlar el look and feel de las pginas. Nunca especifique nombres y tamaos de fuentes directamente en el cdigo .aspx. Esto ayudar a cambiar la capa UI de la aplicacin fcilmente en el futuro. Tambin, si se quiere personalizar la interface de usuario para cada cliente, sera tan sencillo como cambiar la hoja de estilo para ese cliente. (UTILIZAR TEMAS)

Comentarios
Incluya comentarios de buena calidad, con significado claro que facilite el mantenimiento del cdigo. Tenga en cuenta lo siguiente:

(COLOCAR LAS REGLAS DE SAND CASTER)

1.

Los comentarios se deben colocar en idioma ingls.

2.

No sobre sature el cdigo con comentarios.

3.

Use // o /// para comentar el cdigo. Evite el uso de /* */.

4.

Coloque comentarios solo cuando sea requerido. Un buen cdigo por lo general tiene pocos comentarios:

a. b.

Si todas las variables y mtodos tienen identificadores o nombres auto-descriptivos, no es necesario el uso de comentarios en estas declaraciones. No escriba comentarios si el cdigo es fcilmente legible y comprensible.

5.

Si se cambia el cdigo, tambin es necesario cambiar los comentarios para evitar confundir a los programadores que hagan la manutencin del cdigo en el futuro. En algunos casos, los programadores utilizan artificios del lenguaje para ahorrarse lneas de cdigo o para escribir lgica con el menor nmero posible de lneas. Sin embargo, utilizar estas facilidades a veces confunde a otros programadores. En estos casos, es recomendable incluir comentarios aclaratorios o explicativos sobre los artificios utilizados.

6.

7. 8.

Si se utiliza lgica demasiado compleja o rara, se debe documentar muy bien. Si se realizan inicializaciones raras como variables numricas en 0 o -1, etc. documente de forma clara la razn para asignar dichos valores. Realice chequeos ortogrficos sobre los comentarios y tambin asegrese de utilizar la gramtica correcta

9.

Uso de Excepciones
1. Nunca coloque un catch que no haga nada. Si se hace este tipo de cosas, si se oculta una excepcin, nunca se podr conocer si la excepcin ocurri o no y sobretodo se pueden generar inconsistencias en los datos. Los desarrolladores usan esto para ignorar errores insignificantes pero esto puede ser altamente riesgoso.

2.

Siempre se debe tratar de evitar usar excepciones porque son costosas en cuanto a procesamiento. En lugar de esto, los desarrolladores deben chequear programticamente todas las condiciones de error posible para evitar el uso de excepciones. En cualquier caso, realizar un catch de una excepcin y no colocar lgica para realizar el tratamiento de la excepcin, no es permitido. En el peor de los casos, por lo menos se debe registrar la excepcin en un log.

3.

En caso de excepcin, encapsule o reemplace el mensaje de error que lanza el Framework por un mensaje ms amigable para el usuario. Sin embargo se debe registrar en un log todos los detalles del error, incluyendo la fecha y hora en que se produjo, nombre del mtodo o bloque lgico que la produjo, nombre de la clase, etc.

4.

Siempre capture en el catch excepciones especficas y no genricas:

Forma correcta:
public void ReadFromFile ( string fileName )

{ try { // read from file. } catch (FileIOException ex) { // log error. // re-throw exception depending on your case. throw; } }

Forma incorrecta:

public void ReadFromFile ( string fileName ) { try { // read from file. } catch (Exception ex) { // Catching general exception is bad... we will never know whether // it was a file error or some other error. // Here you are hiding an exception. // In this case no one will ever know that an exception happened. return ""; } }

5.

Cuando propague una excepcin a las capas superiores, use la primitiva throw sin especificar el origen de la excepcin. De esta forma, se preserva toda la traza de la excepcin.
Forma correcta:

catch { // do whatever you want to handle the exception throw; }

Forma incorrecta:

catch (Exception ex) { // do whatever you want to handle the exception throw ex; }

6.

No escriba bloques try-catch muy largos. Si se requiere, escriba bloques try-catch para cada tarea que realice y encierre nicamente dentro del try-catch las partes especficas de cdigo que pueden ser vulnerables a error. Esto facilitar encontrar el cdigo que est generando el error. Escriba las propias clases de excepciones usando la facilidad que ofrece el Enterprise Application Block. Nunca herede las excepciones propias de la clase SystemException. En vez de esto, se debe heredar de ApplicationException.

7. 8.

Bibliografa
1. Lance Hunt, C# Coding Standards for .NET (Marzo 2007) 2. http://www.dotnetspider.com, C# Coding Standards and Best Programming Practices