Propuesta de Estándar de desarrollo o codificación (Segunda Entrega) #programacion

Las técnicas de codificación están divididas en tres secciones:

• Nombrado
• Documentación Interna (Comentarios)
• Formato

Nombrado

El esquema de nombres es una de las ayudas más importantes para entender el flujo lógico de una aplicación. Un nombre debe más bien expresar el «qué» que el «cómo». Si se utiliza un nombre que evite referirse a la implementación se estará conservando la abstracción de la estructura ya que la implementación está sujeta a cambios, de esta manera se describe que hace la estructura y no como lo hace.

Por ejemplo es más claro nombrar un procedimiento de acceso a datos SeleccionarRegistro() que RealizarConsultaSelect(), porque lo que importa es que se supone que hace el método y no como lo hace.

Otra directiva es la de utilizar nombres tan largos como para que se entiendan pero a la vez tan cortos como para que no den información irrelevante.

Estructuras (namespaces, procedimientos, clases, interfaces y propiedades)

• Los nombres de todas las estructuras de código deben estar en el mismo idioma.

• Los namespaces deben empezar por el nombre de la compañía seguido del proyecto y la capa:

Namespace Ejemplo.Contabilidad

Namespace Ejemplo.Contabilidad.Core

• El nombre del ensamblado y el namespace root deben ser idénticos.

• Evite el uso de nombre completamente cualificado

• El nombre de la clase y el archivo fuente deben ser iguales.

• En la POO es redundante incluir nombres de clases en el nombre de las propiedades de clases, como por ejemplo Rectángulo.RectánguloArea, en su lugar, utilice Rectángulo.Area, pues el nombre de la clase ya contiene dicha información.

• Utilice la técnica verbo-sustantivo para nombrar procedimientos que ejecuten alguna operación en un determinado objeto, como por ejemplo BuscarEmpleados().

• Empiece los nombres de clase y propiedades con un nombre, por ejemplo CuentaBancaria, la primera letra de cada palabra debe ser mayúscula.

• (PASCAL  para tipos, métodos y constantes)

Public Class SomeClass

Const DefaultSize As Integer = 100

Public Sub SomeMethod()

End Sub

End Class

• Empiece los nombres de interfaz con el prefijo «I», seguido de un nombre o una frase nominal, como IComponente, o con un adjetivo que describa el comportamiento de la interfaz, como IPersistible.

• Evite colocar valores explícitamente a los enum.

• Evite usar una función como parámetro en una condición. Asigne el valor a una variable local.

• No use cadenas de texto en hardcode para presentar información a usuarios. Use archivos de recurso.

• Nunca use cadenas de configuración de la aplicación en hardcode. Use archivos de configuración.

• Cuando construya cadenas de texto largas use StringBuilder No string

• Todos los recursos deben ser referenciados por ruta relativa.

Variables

• Las variables miembro se escriben con la primera letra de cada palabra en mayúscula a excepción de las variable miembro privadas. Las Variables internas o de bloque deben ir en minúscula. En el caso de las variablesmiembro privadas, se debe utilizar el prefijo “m_” sumado al nombre de la variable (m_variable).

• Es recomendado que las variable booleanas contengan una palabra que describa su estado: puedeEliminarse, esGrande, tieneHijos, etc. Y siempre se debe referir al estado verdadero: tieneCredito en cambio de noTieneCredito

• Incluso para el caso de una variable de poco uso, que deba aparecer sólo en unas cuantas líneas de código, emplee un nombre descriptivo. Utilice nombres de variables de una sola letra, como i o j sólo para índices (ciclos for).

• No utilice números o cadenas literales, como por ejemplo For i = 1 To 7. En su lugar, emplee constantes con nombre, del tipo For i = 1 To Enumeracion.length para que resulten fáciles de mantener y comprender.

(Use el prefijo (m_)  y continúe con PASCAL para los miembros privados)

Private Sub MyMethod(ByVal someNumber As Integer)

Dim number As Integer

End Sub

Parámetros

Los parámetros siguen el mismo estándar de las variables

Tablas

• Cuando ponga nombres a tablas, hágalo en singular. Por ejemplo, use Empleado en lugar de Empleados.

• Cuando ponga nombre a las columnas de las tablas, no repita el nombre de la tabla; por ejemplo, evite un campo llamado FacturaFecha de una tabla llamada Factura.

• No incorpore el tipo de datos en el nombre de una columna.

Microsoft SQL Server

• No ponga prefijos sp_ a los procedimientos almacenados, ya que se trata de un prefijo reservado para la identificación de procedimientos almacenados de sistemas.  Use USP_.

• No ponga prefijos fn_ a las funciones definidas por el usuario, ya que se trata de un prefijo reservado para funciones integradas.  Use UFN_

• No ponga prefijos xp_ a los procedimientos almacenados extendidos, ya que se trata de un prefijo reservado para la identificación de procedimientos almacenados extendidos.

• Los nombres de los campos deben empezar por Mayúscula.

• Evite colocar lógica en los procedimientos almacenados. ASP.Net y Web Services

• Evite colocar código directo en la pagina use el archivo de código oculto.

• El código oculto debe llamar a un componente que es que tiene la lógica de negocio.

• Siempre verifique que las session variables no están en null antes de tener acceso a ellas.

• Almacene las session variables en SQL Server.

• Habilite Smart Navigation en las paginas ASP.Net.

• Envuelva las session Variables en una propiedades.

Comentarios

Uno de los problemas de la documentación de software interna es garantizar que se mantengan y actualicen los comentarios al mismo tiempo que el código fuente. Aunque unos buenos comentarios en el código fuente no tienen ningún valor en el tiempo de ejecución, resultan valiosísimos para un programador que tenga que mantener una parte de software particularmente compleja.

• Al principio de cada rutina, resulta útil hacer comentarios estándar, repetitivos, que indiquen el propósito de la rutina, las suposiciones y las limitaciones. Un comentario repetitivo podría consistir en una breve introducción que explicara por qué existe y qué puede hacer.

• Evite añadir comentarios al final de una línea de código.

• Evite los comentarios recargados, como las líneas enteras de asteriscos. En su lugar, utilice espacios para separar los comentarios y el código.

• Antes de la implementación, quite todos los comentarios temporales o innecesarios, para evitar cualquier confusión en la futura fase de mantenimiento.

• Use frases completas cuando escriba comentarios. Los comentarios deben aclarar el código, no añadirle ambigüedad.

• Vaya comentando al mismo tiempo que programa.

• Evite comentarios superfluos o inapropiados, como comentarios divertidos al margen.

• Use los comentarios para explicar el propósito del código. No los use como si fueran traducciones literales.

• Haga siempre comentarios al depurar errores y solucionar problemas de codificación, especialmente cuando trabaje en equipo.

• Haga comentarios en el código que esté formado por bucles o bifurcaciones lógicas. Se trata en estos casos de áreas clave que ayudarán a los lectores del código fuente.

• Separe los comentarios de sus delimitadores mediante espacios.

• Cada declaración de variable importante debe incluir un comentario en la misma línea que describa el uso de la variable que se declara.

Formato

El formato hace que la organización lógica del código sea más clara. Si toma el tiempo de comprobar que el código fuente posee un formato coherente y lógico, les resultará de gran utilidad a usted y a otros programadores que tengan que descifrarlo.

Siga las siguientes pautas para establecer el formato:

• Evite albergar múltiples clases en un solo archivo.

• Establezca un tamaño estándar de sangría (por ejemplo, cuatro espacios o una tabulación) y úselo siempre. Alinee las secciones de código mediante la sangría predeterminada.

• Declare una sola variable por línea.

• Agregue los namespaces en orden descendente empezando por los del sistema y terminado por los personalizados o de usuario.

• Una clase debe estar definida en orden descendente de la siguiente manera: Variables Miembro, Constructores, Enumeraciones, Estructuras o Clases anidadas, Propiedades y por último los Métodos.

• Utilice espacios antes y después de los operadores siempre que eso no altere la sangría aplicada al código: numero = 3; en vez de numero=3

• Use espacios en blanco para organizar a su antojo secciones de código. De tal manera que se comprenda la segmentación del código. En casos donde lo amerite utilice regiones.

• Cuando tenga que dividir una línea en varias, aclare que el código sigue en la línea de más abajo mediante un operador de concatenación colocado al final de cada línea, y no al principio.

• Siempre que sea posible, no coloque más de una instrucción por línea, a excepción de los bucles.

• Al escribir en HTML, establezca un formato estándar para las etiquetas y los atributos; como por ejemplo, las etiquetas siempre en mayúscula y los atributos en minúscula

• Cuando escriba instrucciones SQL utilice mayúsculas para las palabras clave: SELECT, UPDATE, WHERE, FROM, etc.

• Coloque las cláusulas SQL principales en líneas separadas, de modo que las instrucciones sean más fáciles de leer y editar.

• Siempre utilice los tipos nativos de cada lenguaje y no los del CTS.

• No compare strings con  “” use string.empty.

• Evite comparar variables booleanas contra false o true.

 

if(puedeEliminarse=true)

Mejor use

If(puedeEliminarse)

 

Adicionales

• Use programas para el control de Código Fuente.

• Nunca declare una sentencia catch vacía.

• Evite anidar bloques try/catch.

• Ordene la captura de excepciones (catch) siempre en orden descendente desde la más particular hasta la más genérica.

• Siempre que sea posible prefiera la validación al manejo de excepciones