NORMAS DE ESTANDARIZACION

MANUAL DEL PROGRAMADOR Fecha: 19-01-2014 Versin 0.0.1

Departamento de TI Neptuno SAC

2

Este documento contiene un conjunto de reglas y convenciones que se debern considerar en el desarrollo del proyecto a fin de asegurar la estandarizacin del mismo.

Son varias las razones por las que debemos aplicar estas reglas y/o convenciones, entre ellas podemos citar:

Facilitar el entendimiento por parte del equipo. Evitar la dependencia de cualquier integrante del equipo. Facilitar la reutilizacin de cdigo. Reducir los errores lgicos en el cdigo y el tiempo en su depuracin.

Reglas Generales

1. La herramienta de desarrollo IDE que se utilizar es Netbeans por ser una

herramienta libre y con funcionalidades tales como: intellisence (autocompletar),

detector de sintaxis, funcionalidades de edicin avanzadas como bsquedas y

reemplazos en todo el proyecto entre otras que sern de gran ayuda durante la

codificacin; el instalador de la versin ms reciente puede descargarse desde:

http://netbeans.org/downloads/index.html

2. La nica persona responsable de agregar recursos tales como iconos, libreras

externas, imgenes, etc. es el administrador de recursos. Si necesita algo que no

lo tenemos pngase en contacto con sta persona.

3. Si necesita alguna funcin para un propsito general y no existe dentro del

archivo general, deber ponerse en contacto con el administrador de recursos

para su implementacin.

4. Las validaciones de formularios (ingreso de datos) cuya informacin es relevante,

se debe hacer tambin desde el lado del servidor debido a que existen

herramientas que permiten saltar las validaciones desde lado del cliente con

javascript, por ejemplo en Mozilla Firefox mediante Firebug se puede cambiar las

propiedades de los objetos, quitar fracciones de cdigo javascript, anular

validaciones de ciertos objetos de los formularios, etc.

5. Queda totalmente prohibido el uso de herramientas no aprobadas por la jefatura.

6. Si desconoce algo, solicite apoyo a su compaero.

7. En lo posible trate de mantener un ambiente de armona y trate de llevarse bien

con todos.

Departamento de TI Neptuno SAC

3

Organizacin de los Archivos

La estructura de carpetas del proyecto deber ser tal como se puede apreciar en el

siguiente grfico:

Fig 1.- Estructura de carpetas

Dnde:

app: Carpeta que contiene todos los archivos de la aplicacin.

app/class: Contiene las carpetas de cada mdulo; y estos a su vez contienen

los archivos de clase de cada uno de ellos; considerando que casi siempre se

crear una clase por cada tabla del modelo de base datos, aunque

principalmente para las tablas maestras. Por ejemplo:

app/class/gen : Contiene las clases comunes para la aplicacin.

app/class/ven : Contiene las clases para el mdulo de ventas.

css: Contiene los archivos de hojas de estilo que no estn directamente

relacionado con el diseo.

Departamento de TI Neptuno SAC

4

app/interface: Contiene las carpetas de cada mdulo; y estos a su vez

contienen los archivos de interfaz de cada uno de ellos. Por ejemplo:

app/interface/gen: Contiene los archivos de interfaz las clases comunes

para la aplicacin.

app/interface/ven: Contiene los archivos de interfaz para el mdulo de

ventas.

app/js: En esta carpeta se almacenan los archivos javascript que no estn

directamente relacionado con del diseo.

app/lang: En esta carpeta se almacenan los archivos de mensajes.

app/mysql: Contiene los archivos relacionados con la conexin a la base de

datos. As mismo aqu se ubican los archivos logs para almacenar los

mensajes por error.

theme: En sta carpeta se almacena el framework para el diseo.

tools: En sta carpeta se almacenan herramientas externas.

Departamento de TI Neptuno SAC

5

Convenciones de Codificacin

1. Declarar las variables de usuario

Como regla general, todas las variables de usuario debern ser declaradas antes de

utilizarlas, por ejemplo el siguiente ejemplo es incorrecto

lo correcto sera, primero declarar la variable con el valor vacio:

Departamento de TI Neptuno SAC

6

2. Emplear comillas simples

Se deben emplear comillas simples en el cdigo PHP; las comillas dobles estn

reservadas para las etiquetas html.

Por ejemplo:

3. Indentar el cdigo

Es una buena costumbre aplicar sangras al cdigo para facilitar la lectura del mismo,

por ello se recomienda utilizar una herramienta de desarrollo como Netbeans para

hacer sta tarea en forma rpida.

Como regla, se deber utilizar el estilo K&R1, donde la caracterstica ms resaltante

es que las llaves se abren en la misma lnea de declaracin de la orden, indentando

los siguientes pasos al mismo nivel que la llave y cerrando la llave en el mismo nivel

que la declaracin.

Se debern utilizar 4 espacios para las tabulaciones; por ello s est empleando una

herramienta de desarrollo como Netbeans se recomienda realizar la configuracin

respectiva.

Veamos un ejemplo:

function saludar($val){

if($val == 1) {

echo Hola!;

} else {

echo Chau!;

}

}

1 El estilo K&R, fue llamado de esta forma porque fue usado por Kernighan y Ritchies en su libro The C

Programming Language. Se trata de abrir la llave en la misma lnea de declaracin de la orden, indentando

los siguientes pasos al mismo nivel que la llave y cerrando la llave en el mismo nivel que la declaracin.

Departamento de TI Neptuno SAC

7

4. Utilizar nombres de variables apropiadas

Es importante elegir apropiadamente los nombres de las variables. Variables

pobremente nombradas dificultan la lectura del cdigo fuente y su comprensin.

Todas las variables de usuario deben nombrarse con minsculas, s se utilizan

nombres compuestos, a partir de la segunda palabra la primera letra debe ser en

maysculas.

La eleccin del nombre de una variable debe ser un mnemnico, designado para

indicar a un observador ocasional su funcin. Los nombres de variables de un solo

carcter se deben evitar, excepto para variables ndices temporales. Nombres

comunes para variables temporales son $i, $j, $k, $m, y $n para enteros; $mensaje,

$e, $html para caracteres.

Ejemplos:

5. Nombres de clases y mtodos

Los nombres de clases deben ser sustantivos. De preferencia el nombre de la clase

debe ser igual al nombre de la tabla de la base de datos si es el caso y en

minsculas; cuando son compuestos, la primera letra de cada palabra a partir de la

segunda palabra deber ser en maysculas. Intente mantener los nombres de las

clases simples y descriptivas. Use palabras completas, evite acrnimos y abreviaturas

(a no ser que la abreviatura sea mucho ms conocida que el nombre completo.

Para el caso de los mtodos, estos deben ser verbos y estar escritos en minsculas;

cuando son compuestos tendrn la primera letra en maysculas a partir de la

segunda palabra.

Por ejemplo:

Departamento de TI Neptuno SAC

8

otro ejemplo:

En lo posible emplear nombres de variables que tengan relacin con el tipo de datos

que devuelven las consultas por ejemplo en el siguiente cdigo empleamos

Departamento de TI Neptuno SAC

9

$sql_alumnos para guardar la instruccin sql que ejecutaremos en la siguiente

instruccin:

6. Constantes y variables globales

Las constantes predefinidas y las variables globales deben nombrarse con todos los

caracteres en maysculas y las palabras separadas por "_". Existe un archivo de

configuracin el cual contiene las constantes generales del proyecto, todas las

constantes de este archivo empiezan con GL.

Por ejemplo:

Departamento de TI Neptuno SAC

10

7. Comentarios

Archivos PHP: Deben emplearse comentarios siempre que sea necesario para

explicar brevemente la funcionalidad y el propsito del archivo php a fin de que el

resto del equipo le sea ms fcil entender el cdigo.

Se recomienda comentar los mtodos de las clases y funciones ms complejas, se

deben incluir comentarios para describir la funcionalidad del mtodo, as mismo

describir brevemente cada uno de los parmetros del mtodo o funcin.

Ejemplos de comentarios:

Archivos Javascript: Considere las mismas reglas de comentarios que los archivos php.

Archivos CSS: Los archivos de hojas de estilos tambin deben comentarse tal como en

los archivos php y javascript, se recomienda organizar las hojas de estilos en bloques de

tal forma que solo sea necesario colocar comentarios al inicio del bloque para indicar la

Departamento de TI Neptuno SAC

11

zona donde se debern aplicar dichos estilos o describir brevemente la funcionalidad de

los mismos.

8. Hbitos varios

Parntesis : En general es una buena idea usar parntesis en expresiones que

involucran a distintos operadores para evitar problemas con el orden de

precedencia de los operadores. Incluso s parece claro el orden de precedencia

de los operadores podra no ser as para otros, no se debe asumir que otros

programadores conozcan el orden de precedencia, por ejemplo

if (a == b && c == d) // EVITAR

if ((a == b) && (c == d)) // CORRECTO

Valores de retorno: Intente hacer que la estructura del programa se ajuste a su

objetivo. Ejemplo:

if ($result) {

return true;

} else {

return false;

}

Lo anterior se debe hacer de la siguiente manera:

return $result;

Del mismo modo,

if ($x > $y) {

return x;

}

return y;

se debe escribir usando el operador condicional ?:

return ($x > $y ? x : y);