LINQ TO AMAZON. Estándar de Implementación. Versión 1.2

Transcripción

1 LINQ TO AMAZON Estándar de Implementación Versión 1.2 Historia de revisiones Fecha Versión Descripción Autor 22/08/ Creación del documento Guillermo Pérez 23/08/ Actualización del documento Fabrizio Ciccardini 07/09/ Modificaciones. Convenciones Generales Guillermo Pérez Estándar de Implementación Página 1 de 7

2 Contenido 1. CONVENCIONES GENERALES CONVENCIONES ESPECÍFICAS VARIABLES CONSTANTES INDENTACIÓN OTROS INTERFACES CLASES ATRIBUTOS MÉTODOS PARÁMETROS EVENTOS RETORNO DE VALORES EXCEPCIONES COMENTARIOS EMBEBIDOS UTILIZANDO XML... 6 Estándar de Implementación Página 2 de 7

3 1. Convenciones Generales El código de la aplicación deberá estar en idioma Inglés (inclusive los comentarios). 2. Convenciones Específicas Al igual que lo especificado en el documento de Estándar de Doc. Técnica, se utilizarán las técnicas lower case camel y upper case camel para establecer los diferentes criterios de definición Variables Nombres: deben estar compuestos por caracteres alfanuméricos y deben cumplir con el formato lower case camel. Es recomendable utilizar nombres descriptivos, a excepción de por ejemplo i, j o k para índices, debido a que son utilizados frecuentemente como tales en el ámbito de la programación. Ejemplo: myvariable Comentarios: en la línea inmediatamente anterior a la definición de la variable, debe incluirse un comentario que brinde una breve descripción del uso que se le dará a la misma. Declaraciones: dentro del alcance de una variable no se podrá definir otra con el mismo nombre, evitando así lugar a la confusión y facilitando la verificación del código Constantes Nombres: deben estar compuestos por caracteres alfanuméricos y deben estar todos sus caracteres en mayúscula. En los casos en que es necesario utilizar dos o más palabras, deben separarse mediante un guión bajo. Ejemplo: MY_CONSTANT Comentarios: en la línea inmediatamente anterior a la definición de la constante, debe incluirse un comentario que brinde una breve descripción del uso que se le dará a la misma. Declaraciones: deberá definirse inmediatamente después de la declaración del NameSpace una región en la cual se definan todas las constantes a utilizar dentro del alcance del mismo Indentación La indentación será como se muestra a continuación con un ejemplo genérico, teniendo en cuenta particularmente la indentación con llaves. Estándar de Implementación Página 3 de 7

4 namespace MyNameSpace public class MyClass() // Commentary on a single line If (condition) else /* * Commentary * on two or more lines */ for( ; ; ) - Para todas las estructuras de control deberá tenerse en cuenta el criterio utilizado para If-else y For en el ejemplo dado anteriormente. - En ningún caso deberán omitirse las llaves de apertura y clausura, haciendo referencia particularmente a casos en que estructuras de control contienen una única sentencia. - Como se muestra en el ejemplo, las llaves de apertura y clausura se encuentran cada una en una línea, separadas del código. La única excepción será para las operaciones que tengan una sola sentencia (ej. get return x; ). - Notar que al comienzo de cada línea de comentario debe dejarse un espacio, ya sea después de // o del *. - Cada indentación de código se realiza con una tabulación, no pudiendo utilizarse espacios en reemplazo de ésta. - Dejar una línea en blanco para facilitar la comprensión del código en los siguientes casos: Antes de los comentarios, permitiendo así identificar fácilmente al comentario con el código que se encuentra a continuación del mismo. Entre la definición de Clases, Métodos, Interfaces, etc. En cualquier otro caso que se considere necesario para brindar claridad al código. Estándar de Implementación Página 4 de 7

5 3. Otros En general, para todos los casos presentados a continuación, los comentarios deben realizarse en la línea inmediatamente anterior a la definición de la interfaz, clase, etc. Debe incluirse un comentario que brinde una breve descripción del uso que se le dará a la misma Interfaces Nombres: deben estar compuestos por caracteres alfabéticos y utilizarse el criterio upper case camel, comenzando siempre con el prefijo I. (Particularmente tampoco utilizar el guió bajo _ ) Ejemplo: IMyInterface - Utilizar abreviaturas que faciliten la legibilidad del código, pero no de manera que la entorpezcan. - Utilizar nombres preferentemente idénticos para clases e interfaces relacionada, con la excepción del prefijo I en el nombre de la interfaz Clases Nombres: deben estar compuestos por caracteres alfabéticos y utilizarse el criterio upper case camel. (Particularmente tampoco utilizar el guió bajo _ ) Ejemplo: MyClass - Utilizar abreviaturas que faciliten la legibilidad del código, pero no de manera que la entorpezcan. - No utilizar prefijos, por ejemplo, para una clase Xxx no utilizar ClassXxx. - Cuando se considere apropiado, puede concatenarse al nombre de una clase derivada el nombre de la clase de la cuál deriva, si es que ello facilita la legibilidad del código Atributos Nombres: deben estar compuestos por caracteres alfabéticos y utilizarse el criterio upper case camel. (Preferentemente utilizar abreviaturas que faciliten la legibilidad del código, pero no de manera que la entorpezcan) Ejemplo: MyAttribute - Declararlos como private Métodos Nombres: deben estar compuestos por caracteres alfanuméricos y utilizarse el criterio upper case camel. Ejemplo: MyMethod Estándar de Implementación Página 5 de 7

6 3.5. Parámetros Nombres: deben estar compuestos por caracteres alfanuméricos y utilizarse el criterio lower case camel. - Utilizar nombres que sean descriptivos en cuanto al significado del parámetro más que a su tipo Eventos Nombres: deben estar compuestos por caracteres alfanuméricos y utilizarse el criterio upper case camel. - Utilizar el sufijo EventHandler en nombres de controladores de eventos. - Especificar dos parámetros denominados sender y e. El parámetro sender representa al objeto que produjo el evento. Este parámetro deberá ser siempre de tipo object, aunque sea posible utilizar un tipo más específico. El parámetro e es una instancia de una clase de eventos, que encapsula el estado asociado con el mismo. En éste caso deberá utilizarse una clase de eventos apropiada y específica para el tipo de parámetro e. Deberá agregarse al nombre del tipo el sufijo EventArgs Retorno de valores La sentencia return debe realizarse una única vez, facilitado así la comprensión del código Excepciones - Se recomienda utilizar los tipos de excepciones predefinidos, excepto en los casos en que se quiere realiza una acción particular mediante programación. Por ejemplo, tiene sentido definir una excepción FileNotFoundException cuando un archivo no es encontrado, ya que puede quererse crear el archivo que falta en vez de dar un error. - El mensaje de la excepción debe ser lo más explicativo posible. - Al momento de capturar las excepciones, se deberán capturar en orden jerárquico, comenzando desde la más específica a la más genérica Comentarios embebidos utilizando XML Se tiene en cuenta la posibilidad de realizar los comentarios referentes a las clases y métodos utilizando los Comentarios de documentación XML que brinda el IDE (Entorno de desarrollo integrado), facilitando el uso de los mismos a través de la característica IntelliSense. Esta función permite que dichos comentarios se muestren a través de las características de IntelliSense como Lista de miembros, Información de Estándar de Implementación Página 6 de 7

7 parámetros o Información rápida ; brindando así amigabilidad al momento del desarrollo de la aplicación. Debido a las características del Proyecto, el uso de éste tipo de comentarios dependerá de la validación o no de su uso por parte del Cliente, pues entendemos que podría ser contraproducente al momento de leer el código. (En caso de que se requiera su uso, deberán definirse las etiquetas que se deberán usar) Estándar de Implementación Página 7 de 7