NORMAS DE ESTANDARIZACION

MANUAL DEL PROGRAMADOR

Fecha:
Versin

19-01-2014
0.0.1

Departamento de TI

Neptuno SAC

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

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

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

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
<?php
if(isset($_SESSION[usuario])){
$mensaje = Si existe;
}
else{
$mensaje = No existe;
}

echo $mensaje;
?>

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

<?php
$mensaje = ;
if(isset($_SESSION[usuario])){
$mensaje = Si existe;
}
else{
$mensaje = No existe;
}

echo $mensaje;
?>

Departamento de TI

Neptuno SAC

2. Emplear comillas simples

Se deben emplear comillas simples en el cdigo PHP; las comillas dobles estn
reservadas para las etiquetas html.
Por ejemplo:
<?php
$saludo = Hola mundo de la programaci&oacute;n,;
$saludo .= como est&aacute;n el d&iacute;a de hoy.;
echo $saludo;

$codigo = $_REQUEST[cod];
?>

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!;
}
}

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.
6

Departamento de TI

Neptuno SAC

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:
<?php
$saludo = Hola a todos;
$codigo = A-100;
$apellidoPaterno = $_REQUEST[txtApellidoPaterno];
for($i=1; $i<=10; $i++){
echo contando ->.$i;
}
$suma = 0.00;
$total = 0;
?>

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

<?php
class persona {
public function __construct() {
}
public function __destruct() {
}
public function agregarPersona(

$dni,
$apellidoPaterno,
$apellidoMaterno,
$email) {

}
}
?>

otro ejemplo:
<?php
class tramiteDocumentario {
public function __construct() {
}
public function __destruct() {
}
public function consultarDocumento($idDocumento) {
}
public function registarDocumento($data) {
.
.
.
$sql = CALL tra_registrarDocumento(
.$data[unoperOrigen].,
.$data[unoperDestino].,
.$data[usuarioOrigen].,
.$data[usuarioDestino].);
.
$result = mysqli_query($link, $sql);
.
}
}
?>

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

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

instruccin:

<?php
class alumno {
public function __construct() {
}
public function __destruct() {
}
public function buscarAlumnos(
$tipoBusqueda,
$buscar) {

$sql_alumnos = CALL buscarAlumno(

$tipoBusqueda,
$buscar);
.
$result = mysqli_query($link, $sql_alumnos);

}
}
?>

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:
<?php
/* constantes predefinidas */
define(GL_RUTA_SERVIDOR, $_SERVER['DOCUMENT_ROOT']. /cad/);
define(GL_URL_SERVIDOR,
http://.$_SERVER['HTTP_HOST'].
/cad/);
/* variables globales*/
$TITULO_PAGINA = Mantenimiento de Clientes;
?>

Departamento de TI

Neptuno SAC

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:
<?php
/*
Permite eliminar el usuario de la base de datos sin chance
a recuperar la cuenta, se eliminarn todas sus actividades,
contactos y mensajes.
*/
include_once(class/usuario.class.php);
$c_usuario = new usuario();
$existe = $c_usuario>consultarExisteUsuario($_REQUEST[id]);
if($existe){
//eliminar todo el historial de comentarios, contactos
y //mensajes
$result = $c_usuario>eliminarHistorial($_REQUEST[id]);
if($result){
//cargar la pantalla inicial de logeo
header(Location: ../login.php);
}
else{
include_once(mensajes.php);
echo mensajeError(401);
}
}
?>

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
10

Departamento de TI

Neptuno SAC

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);

11