PROCESO DE

CONSTRUCCIÓN
DEFINICIONES

1. INTRODUCCIÓN
En el presente documento se recogen una serie de sugerencias para llevar un
desarrollo de aplicaciones en lenguaje PHP más ordenado y que dé como
resultado aplicaciones que permitan una mayor facilidad de trabajo,
mantenibilidad, sostenibilidad y escalabilidad.
En este documento se intenta cubrir entre otros elementos, desde el patrón de
diseño que se debe utilizar, organización de directorios, los nombres de los
ficheros, identación, comentarios, declaraciones, sentencias, espacios en
blanco.
Con todo esto se busca que cada persona que ingrese nueva al desarrollo en
PHP logre una fácil adaptación y que de igual forma no le sea demasiado
complicado el tomar para mantenimiento cualquier desarrollo que otro haya
realizado; de esta forma también facilitar la difusión del conocimiento entro los
diferentes desarrollos.

Versión 1.0 Mayo 18 de 2007

Página 1 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

2. ANTECEDENTES
La información aquí presentada e tomada como referencia de otras
documentos existentes sobre estándares de desarrollo, se adicionan en este
documento para tener referencia de la importancia de lograr una unificación
del trabajo de todos y cada uno de los miembros del equipo de desarrollo.
Entre las razones a destacar por las que se deben seguir unas normas, están:
• El 80% del costo del ciclo de vida de una pieza de software es el
mantenimiento.
• Raramente un software es mantenido por el autor original.
• Las convenciones incorporan legibilidad al código, permitiendo que los
ingenieros entiendan el nuevo código mucho más rápidamente.
• Si se proporciona el software como un producto, ha de asegurarse que
está igual de empaquetado y limpio que cualquier otro que se haya hecho.

Versión 1.0 Mayo 18 de 2007

Página 2 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

3. Patrón de diseño
Para lograr una mayor organización en el desarrollo y con el fin de poder
delimitar claramente las porciones de código que se manejan en las
aplicaciones se plantea seguir el patrón de diseño MVC (Modelo-vista-
controlador), de esta forma se separa todo lo que es código de presentación
HTML, lógica de negocio y acceso a base de datos.
Para esto se plantean las siguientes pautas:
• Todo método que requiera acceso directo a la base de datos debe estar
dentro del archivo de modelo.
• Toda restricción de acceso o almacenamiento en base de datos debe estar
dentro del archivo de modelo.
• Todo código que sea HTML debe estar definido en el archivo de vista.
• La comunicación entre los archivos modelo y los archivos vista se debe
desarrollar en al archivo controlador.

Dentro del análisis de este patrón se encontró como herramienta útil para
desarrollo la librería xajax, el cual facilita el desarrollo del archivo controlador
facilitando la transferencia de información entre modelo y vista, adicional
también facilita la inclusión de AJAX dentro de las aplicaciones y de esta forma
lograr comunicación asíncrona entre cliente y servidor y así no tener que
recargar las páginas por completo.

Versión 1.0 Mayo 18 de 2007

Página 3 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

4. Organización de directorios y archivos

Se plantea la siguiente organización de directorios y archivos para lograr una
mayor organización de las aplicaciones, de la siguiente forma:

Aplicación

Directorio Resumen
Administración En esta directorio se adicionarían los módulos que tengan
como referencia tareas por ejemplo de CRUD dentro de la
aplicación.
Config Directorio para el almacenamiento de los archivos de
configuración requeridos para el correcto funcionamiento
de la aplicación.
Includes Directorio en el cual se deben colocar los archivos que se
deben incluir a lo largo de la aplicación para su
funcionamiento. Ejemplo: sql_db.php.
En este directorio debe existir un subdirectorio javascript
para colocar aquí los archivos javascript de uso general en
toda la aplicación.
Modulos Directorio en el cual se realizará el almacenamiento de los
diferentes módulos que componen la aplicación.
Library Directorio en el cual se incluirán las clases o librerías
externas que se utilizan dentro de la aplicación. Ejemplo:
PEAR, xajax, etc.

Versión 1.0 Mayo 18 de 2007

Página 4 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

Modulo

Directorio Resumen
Controlador Directorio de almacenamiento de archivo controlador del
módulo.
javascript Directorio para incluir los archivos javascript que son
utilizados específicamente por el módulo.
Css Directorio para almacenamiento de los archivos de estilos
específicos del módulo.
modelo Directorio en el cual se almacenarán los archivos que
realizan las operaciones o que contienen las operaciones
directas sobre base de datos.
vista Directorio par almacenamiento de los archivos que sean
html.

Versión 1.0 Mayo 18 de 2007

Página 5 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

5. Librerías
Se plantea el uso de las siguiente librerías para el trabajo en aplicaciones,
estas se sugieren dado que ya tienen un camino recorrido en cuanto a pruebas
y rendimiento.
• PEAR, conjunto de clases que ofrecen diversas funcionalidades que
facilitan la presentación de información.
• XAJAX, librería utilizada para utilización de Ajax en una forma más clara y
sencilla.
• Jquery, librería utilizada para el manejo de eventos dentro de los archivos
html.

6. Nombramiento de archivos
Los archivos serán nombrados de la siguiente forma:
Todo en minúscula, separador de palabra guion bajo.
Ejemplo:
ingreso_detalle

7. Nombramiento de archivos adición

A cada uno de los archivos se adicionará a su nombre una abreviatura para
definir su tio dentro del modelo MVC, así:
 Modelo: DAO
 Vista: VIEW
 Controlador: CONT
Ejemplos:
informe_general_DAO.php;
informe_general_VIEW.php
informe_general_CONT.php

Versión 1.0 Mayo 18 de 2007

Página 6 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

8. Cantidad caracteres por línea

Se plantea un límite de 160 caracteres, de esta forma evitar que se generen
líneas de código demasiado extensas que dificulten su lectura y entendimiento.

9. Extensión de archivos (no incluye archivos

JavaScript, estilos css)
Archivos de configuración .inc.php
Archivos adicionales de configuración .ini
Archivos de templates .phtml
Todos los demás .php

10. Identación (espacios)

Se plantea una identación de 2 espacios en blanco, esto con el fin de facilitar la
lectura y entendimiento del código.

Identación en los case de switch

Sí.

11. Comentarios iniciales

A continuación se listan y describen las etiquetas que se utilizaran en el

proceso de comentariado del código, esto ayudará en gran medida a la
extracción de una buena documentación con el software Doxygen. Todas las
etiquetas se realizan por fuera de la función.

Etiquetas:
Versión 1.0 Mayo 18 de 2007
Página 7 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

➢ @brief: Breve descripción de la función, método o clase, su sintaxis es

la siguiente:

■ @brief Descripción

Ejemplo:
■ @brief Función inicial para cambiar el formato de las horas
y las fechas en oracle

➢ @param: Parametros de entrada en la función, se utiliza una etiqueta

por cada parámetro, su sintaxis es la siguiente:

■ @param type $nombreVariable Descripción

Ejemplo:
■ @param String $usu Nombre del usuario
■ @param Int $id Gabinete Tipologia

➢ @return: Descripción del dato a retornar, su sintaxis es la siguiente:

■ @return type Descripción

Ejemplo:
■ @return $String Devolvemos una cadena de caracteres

➢ @note: Se utiliza para escribir algo muy importante sobre la función,

método o clase, su sintaxis es la siguiente:

Versión 1.0 Mayo 18 de 2007

Página 8 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

■ @note Descripción

Ejemplo:
■ @note Esta es una nota de prueba

➢ @see: La utilizamos para referenciar otros métodos, su sintaxis es la

siguiente:

■ @see nombreMetodo()

Ejemplo:
■ @see loadModel()

➢ @throws: Se utiliza para escribir Excepciones, su sintaxis es la

siguiente:

■ @throws CHttpException

Clases:

Para las clases el comentario se hace antes de la clase y de la siguiente

manera.

➢ @brief NombreClase Descripción

Versión 1.0 Mayo 18 de 2007

Página 9 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

Ejemplo:
● @brief ConsultasController Clase del controlador para el módulo de las
consultas en Altius
La herramienta que se utilizará para generar la documentación es DOXYGEN, la
cual tiene un manual de instalación, pasos y demás en la siguiente ruta:

https://drive.google.com/a/compuredes.com.co/?tab=mo#folders/0BwK-
xeYeez1qczdyTXNFV0luZlE

12. Declaraciones

Número por línea

Se recomienda colocar solamente una declaración por línea y se insta a
comentarla siempre. Por ejemplo:

var $nivel; // nivel de indentación

var $nombre; // nombre de la tabla

13. Utilización de llaves ({)

Clases
En la misma línea de la declaración.
Ejemplo:
class nombreClase () {
}

Métodos
En la misma línea.

Versión 1.0 Mayo 18 de 2007

Página 10 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

Ejemplo:
nombreMetodo () {
}

if; else; elseif; while; do while

Ejemplo:
if () {
}

14. Alineaciones

Alineación else, elseif

Ejemplo:
if () {
} else{
}

Alineación while
Ejemplo:
do {
} while()

Alineación catch
Ejemplo:
try {
} catch (Exception $e) {

Versión 1.0 Mayo 18 de 2007

Página 11 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

15. Espacios en blanco

Se recomienda utilizar colocar espacios en blanco en los siguientes casos:
 Luego de if, else, while, try, catch, asignaciones.
 Espacios en blanco antes y después de (=, ==, <, >=, ., etc)

16. Utilización camel case

Se recomienda la utilización de camelcase para el nombramiento de las
siguientes sentencias, iniciando con minúscula:
 Funciones
 Clases
 Métodos
 Variables

Los puntos del 10 al 15 deben ser configurados en cada uno de los editores
utilizados para la codificación. Los valores aquí presentados viene por defecto
en el IDE Netbeans.

17. Creación configuraciones .

Todas las configuraciones que son necesarias para los diferentes
proyectos se deben registrar en la tabla :

TNEM_CONFIGURACION
La cual tiene la siguiente estructura.

Versión 1.0 Mayo 18 de 2007

Página 12 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

IDCONF = consecutivo de la configuración

IDTIPOLOGIA = código de la tipología a la cual se le configurara o
parametrizará.
TIPOCONFIG= código compuesto entre tipología y nombreconfig, para
identificar dentro del código la configuración de forma más nemotécnica.
Ejemplo LST_CIUDADES configuración que trae las ciudades.
NOMBRECONFIG = Nombre que se le quiera dar a la configuración
para llamarla dentro del código fuente, Ejemplo;
NM_MAX_UPLOAD.
VALORCONFIG = Dato de la configuración.
XMLCONFIG= Se utiliza para configuraciones complejas, con el fin de
no ampliar la estructura de datos.
XMLALTERNO = El objetivo de esta campo es almacenar un valor de
XML que sea muy extenso y se salga del tamaño permitido por Oracle,
este tiene restricción de consultas xml ya que no es un campo xml como
tal, utilizar sólo cuando sea estrictamente necesario.

Ejemplos:

Versión 1.0 Mayo 18 de 2007

Página 13 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

IDCON IDTIPOLOGI TIPOCONFI NOMBRECONFI VALORCO

F A G G NFIG XMLCONFIG

1 110 LST_SEXO Masculino M NULL

2 110 LST_SEXO Feminino F NULL

3 110 LST_PAISES Colombia 57 NULL
4 110 LST_PAISES Ecuador 52 NULL
PARAMETE NM_MAX_UPLO
5 111 R AD_MB 15 NULL
PARAMETE NM_TIMEOUT_
6 111 R SEC 30 NULL
"<?xml version = '1.0' encoding = 'UTF-8'?
><root>
<checklist>
<campo id="605">Fecha</campo>
<campo id="616">Nombre del
paciente</campo>
<campo id="606">Nÿºmero de
documento</campo>
<campo id="617">Entidad
CHKMESA_CON
7 112 CHECK Autoriza</campo>
TROL
<campo id="618">Servicio</campo>
<campo
id="622">Diagnÿ³stico</campo>
<campo id="623">Firma del
especialista</campo>
<campo id="624">Sello de la
entidad</campo>
</checklist>
NULL </root>"
"<?xml version = '1.0' encoding = 'UTF-8'?
><root>
<checklist title="Contrato de comodato de
CHKMESA_FIR archivos">
8 112 CHECK <campo id="605">Fecha</campo>
MAS
<campo id="603">Código</campo>
<campo id="626">El
comodatante</campo>
NULL <campo id="628">Nombre
Versión 1.0 Mayo 18 de 2007
Página 14 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

comodatario</campo>
<campo id="629">Identificación
comodatario</campo>
<campo id="616">Nombre del
paciente</campo>
<campo id="630">Identificación
paciente</campo>
<campo id="607">Dirección</campo>
<campo id="631">Ciudad</campo>
<campo id="632">Entidad
autorizante</campo>
<campo id="633">Bienes</campo>
<campo id="634">Fecha clausulas del
servicio</campo>
<campo id="635">Firma del
comodatario</campo>
<campo id="615">Cedula</campo>
<campo id="636">Huella
dactilar</campo>
</checklist>
<checklist title="Pagare">
<campo id="637">Lugar y fecha de
creación</campo>
<campo id="638">Firma del
otorgante</campo>
<campo id="639">Cedula -
pagare</campo>
<campo id="640">Huella dactilar -
pagare</campo>
</checklist>
<checklist title="Carta de Instruccione">
<campo id="641">Yo - Carta de
Instrucciones</campo>
<campo id="642">Cedula - Carta de
Instrucciones</campo>
<campo id="643">de - Carta de
Instrucciones</campo>
<campo id="644">Constancia se firma -
Carta de Instrucciones</campo>
<campo id="645">Firma del otorgante -
Carta de Instrucciones</campo>
<campo id="646">Cedula - Carta de
Instrucciones</campo>

Versión 1.0 Mayo 18 de 2007

Página 15 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

<campo id="647">Huella dactilar - Carta

de Instrucciones</campo>
<campo id="648">Numero documento -
Carta de Instrucciones</campo>
</checklist>
</root>"

18. Estándar reportes.

La creación de reportes debe cumplir lo siguiente:

1) Debe tener filtros, configurables, con una tabla que indique si es

obligatorio o no (TNEM_CONFIGURACION), o tipo de dato, rango de
fechas.
2) Paginación = 20 registros, el # de registros por página debe estar
almacenado en la tabla de configuración (BD)
3) Filtros sobre el resultado, las columnas del reporte deben permitir otros
filtros adicionales, estándar.
4) Exportación a Excel.

19. Estándar clientes y servicios web.

Clientes:
1) La url donde consumirá los servicios debe estar registrada en la tabla
TNEM_CONFIGURACION.
2) Debe permitir reintentos para consumir (parametrizable)
3) Debe dejar el LOG del consumo tablas (ws_xml_log y ws_traz_lote)

Versión 1.0 Mayo 18 de 2007

Página 16 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

4) Debe permitir relanzar (configuración módulo de respuesta.

5) Debe tener control de excepciones, notificar en errores críticos (sistema
de notificaciones empresarial)
6) Debe trabajar transaccionalmente (en caso de que realice acciones en la
base de datos después de ejecutarse)

Servicios:

1) Debe dejar el LOG del consumo tablas (ws_xml_log y ws_traz_lote)

2) Debe tener estandarizado la tabla de respuesta (errores y proceso
exitoso)
3) Debe tener control de excepciones, notificar en errores críticos (sistema
de notificaciones empresarial)
4) Debe trabajar transaccionalmente: cualquier error que surja debe
devolver los update, Insert, delete, que ejecutó previamente.
5) Validar reglas de negocio, campos obligatorios, consistencia de datos, en
caso de cumplirlas se debe registrar igualmente el LOG y dar respuesta.

20. Estándar entorno de desarrollo.

Los módulos nuevos (ventanas, configuración y demás) se deben crear con

el framework definido por el área de ingeniería de software (Yii
Framework), las demás modificaciones que sean necesarias se realizará
dentro de del sistema actual, se debe quitar la práctica de quemar
configuraciones en el código, el sistema debe ser más paramétrico y
apoyarse en configuraciones.

Versión 1.0 Mayo 18 de 2007

Página 17 de 18
 PROCESO DE
CONSTRUCCIÓN
DEFINICIONES

El IDE de desarrollo definido es: Netbeans, el cual tiene que estar

configurado con el software de control de código definido, además, seguir
las políticas definidas para su correcto funcionamiento y uso.

https://drive.google.com/a/compuredes.com.co/?tab=mo#folders/0BwK-
xeYeez1qRU9fNXVnTnhJVVk

21. Estándar control de excepciones.

El código debe capturar los errores que se puedan presentar, además de

mostrarlos de forma amigable y entendible para el usuario, por tal motivo es
importante el manejo de (Try, catch, finally)

Para ello se debe buscar.

a. Validar campos requeridos
b. Validar tipos de datos.
c. Validar reglas de negocio
d. Presentar mensajes en pantalla.

NOTA: Hablar sobre base de datos, procedimientos, y prácticas.

bootstrap

Versión 1.0 Mayo 18 de 2007

Página 18 de 18