Políticas y Buenas Prácticas de Programación


Políticas y Buenas Prácticas de Programación

  1. Objetivo

Establecer un conjunto de políticas, normas y buenas prácticas que permitan:

Estas políticas aplican a todos los miembros del equipo de desarrollo involucrados en la creación, mantenimiento o revisión de código en cualquier tecnología y proyecto.

    • Estandarización del Código

    • Principios de Diseño

    • Reutilización y Mantenimiento

    • Validaciones

    • Manejo de Errores y Excepciones

    • Legibilidad y Simplicidad

    • Refactorización Continua

    • Antes de subir código

    • Para los Pull Requests

    • Flujo de Validación

Todo commit deberá seguir el siguiente flujo antes de ser fusionado a producción:

    1. Pruebas y verificación por el equipo de QA.

    2. Revisión técnica por un Code Reviewer.

    3. Autorización final antes del merge.

    • Formato de commits

Cada desarrollador debe:

Página nuevaRevisión (Peer Review + Code Reviewer)

Revisión (Peer Review + Code Reviewer)

Asignación de Pares (base)

Rotación semanal

Revisión Cruzada entre Seniors
Reglas Anti‑Cuello de Botella
Checklist Peer Review (rápido) / PROGRAMADOR

  1. Nombres claros, funciones cortas, sin duplicaciones.

  2. Validaciones de entrada y mensajes de error adecuados.

  3. Evitar queries dentro de bucles; revisar índices/joins.

  4. Los archivos coinciden con el alcance.

Checklist Code Reviewer (crítico)

  1. Seguridad: sanitización, queries parametrizadas.

  2. Performance: consultas pesadas detectadas, uso de caché cuando aplica.

  3. Pruebas/CI: linters ok, tests mínimos verdes, build sin warnings críticos.(PENDIENTE)

  4. Higiene del MR: sin cambios ajenos, commits limpios, descripción con rutas/archivos.

Flujo Operativo (resumen)

  1. Dev (misma rama dev) → el programador documenta archivos/rutas tocadas en la tarea.(TRABAJANDO)

  2. Peer Review → el par asignado revisa código + funcionalidad mínima. (INSERT DE REVISIÓN CÓDIGO)

  1. QA → prueba funcional completa. (ÁREA DE QA)

  2. Commit/MR por tarea a pre‑prod → Code Reviewer aplica checklist crítico. (PENDIENTE DE PULL)

  3. Merge a pre‑prod → validación en entorno estable.





Plantilla Base de Pruebas Funcionales

Plantilla Base de Pruebas Funcionales

Este documento sirve como formato estándar para documentar las pruebas funcionales que cada programador debe realizar antes de enviar su desarrollo a QA. Debe completarse para cualquier tipo de tarea (roles, incidencias, métricas, validaciones, creación de doctypes, etc.).

1) Recursos
2) Precondiciones
3) Casos de Prueba Funcionales

Regla: Para cada tarea documentar al menos 3 casos válidos y 1 caso no válido.

Ejemplos de flujos válidos: creación de registro, consulta, modificación.
Ejemplo de flujo no válido: intento con datos inválidos o permisos insuficientes.

4) Casos Negativos / Seguridad
5) Consideraciones (opcional)
6) Rutas / Funciones / Opciones Tocadas
7) Evidencias
Incluir capturas de pantalla de cada caso probado

8) Checklist del Programador

[ ] Evidencias adjuntadas
[ ] Precondiciones cumplidas
[ ] Casos válidos y no válidos documentados
[ ] Rutas/funciones tocadas listadas / DETALLE DE PULL

[ ] Consideraciones (OPCIONAL)

9) Resultado del Peer Review

• Revisor:
• Fecha:
• Observaciones:
• Decisión: Aprobado / Requiere cambios

10) Checklist del Code Reviewer

[ ] Seguridad (inputs sanitizados, queries parametrizadas, CSRF/XSS)
[ ] Performance (consultas optimizadas, uso de caché)
[ ] Arquitectura (respeta MVC, modularidad)
[ ] Higiene del MR (commits limpios, cambios aislados)
[ ] Evidencias revisadas y conformes

 

Ejemplo: https://erp.overskull.com/app/task/TASK-2025-04449

Recursos:


Precondiciones:


Consideraciones:

 

Guía de Estilo y Nomenclatura para Desarrollo

Guía de Estilo y Nomenclatura para Desarrollo

1. Uso de Variables

✅ Ejemplo correcto:

$isActiveUser = true;

$attemptCount = 3;


🚫 Ejemplo incorrecto:

$usuarioActivo = true;

$numeroDeIntentos = 3;

 

2. Uso de Funciones y Métodos

 

✅ Ejemplo correcto:

function getUserById($id) {

    // Código...

}

🚫 Ejemplo incorrecto:

function obtenerUsuarioPorId($id) {

    // Código...

}

 

3. Nomenclatura de Archivos

✅ Ejemplo correcto:

UserMaintenanceModal.php

UserController.php


🚫 Ejemplo incorrecto:

MantenimientoModal.php

UsuarioController.php

 

4. Indentación y Formato

✅ Ejemplo correcto:

function validateUser($user) {

    if ($user->isActive) {

        return true;

    }

    return false;

}


🚫 Ejemplo incorrecto:

function validarUsuario($usuario) {

if ($usuario->activo) {

return true;

}

return false;

}

 

5. Uso de Comentarios

✅ Ejemplo correcto:

/**

 * Calculates the total with applied discount.

 *

 * @param float $subtotal

 * @param float $discount Discount percentage (e.g., 0.15 for 15%)

 * @return float

 */

function calculateTotal($subtotal, $discount) {

    return $subtotal - ($subtotal * $discount);

}


🚫 Ejemplo incorrecto:

// Esta función calcula el total

function calcularTotal($subtotal, $descuento) {

    return $subtotal - ($subtotal * $descuento);

}

 

6. Uso de Constantes

✅ Ejemplo correcto:

define('TIME_LIMIT', 300);

const MAX_ATTEMPTS = 5;


🚫 Ejemplo incorrecto:

define('TiempoLimite', 300);

const max_intentos = 5;


 

 

7. Manejo de Espacios en Blanco

✅ Ejemplo correcto:

if ($isActive) {

    processUser($user);

}




logAction($user);


🚫 Ejemplo incorrecto:

if ($activo) { procesarUsuario($usuario); }

registrarAccion($usuario);

 

8. Longitud Máxima de Funciones

✅ Ejemplo correcto:

function processOrder($order) {

    $user = validateUser($order->userId);

    $discount = calculateDiscount($user->type);

    $total = calculateTotal($order->items, $discount);

    handlePaymentAndStock($order, $total);

    return "Order processed successfully";

}


🚫 Ejemplo incorrecto:

function procesarOrden($orden) {

    $usuario = getUserById($orden->userId);

    if (!$usuario) { throw new Exception("Usuario no encontrado"); }

    $descuento = ($usuario->tipo == "VIP") ? 0.15 : 0.10;

    $subtotal = 0;

    foreach ($orden->items as $item) { $subtotal += $item->precio * $item->cantidad; }

    $total = $subtotal - ($subtotal * $descuento);

    if ($total > 1000) { aplicarPromocion($orden); }

    registrarPago($orden, $total);

    actualizarStock($orden->items);

    enviarConfirmacion($usuario, $orden);

    return "Orden procesada con éxito";

}

Estandarización de Servicios

Estandarización de Servicios

1. Estructura de Respuesta

Todos los servicios deben seguir una estructura de respuesta estándar en formato JSON:

{

    "success": false,

    "message": "Mensaje de servicio",

    "data": []

}


Reglas para la Respuesta:

✅ Ejemplo de Respuesta Exitosa:

{

    "success": true,

    "message": "User retrieved successfully",

    "data": {

        "id": 1,

        "name": "John Doe",

        "email": "johndoe@example.com"

    }

}


✅ Ejemplo de Respuesta con Error:

{

    "success": false,

    "message": "User not found",

    "data": []

}

 

2. Generación de Documentación (Swagger)

✅ Ejemplo de Documentación Swagger en OpenAPI 3.0 (YAML):

paths:

  /users/{id}:

    get:

      summary: Get user by ID

      description: Retrieves a user using their unique ID.

      parameters:

        - name: id

          in: path

          required: true

          schema:

            type: integer

      responses:

        "200":

          description: User retrieved successfully

          content:

            application/json:

              schema:

                type: object

                properties:

                  success:

                    type: boolean

                  message:

                    type: string

                  data:

                    type: object

                    properties:

                      id:

                        type: integer

                      name:

                        type: string

                      email:

                        type: string

        "404":

          description: User not found

          content:

            application/json:

              schema:

                type: object

                properties:

                  success:

                    type: boolean

                  message:

                    type: string

                  data:

                    type: array

                    items: {}

 

3. Códigos de Estado HTTP Estándar

 

4. Seguridad y Buenas Prácticas

 

 

5. Uso de Estructuras de Control

Para mejorar la consistencia y calidad del código, se deben seguir estas reglas al manejar estructuras de control:

Condicionales (if/else)

✅ Ejemplo Correcto:

if not user:

    return {"success": false, "message": "User not found", "data": []}

return {"success": true, "message": "User retrieved", "data": user}


🚫 Ejemplo Incorrecto:

if user:

    return {"success": true, "message": "User retrieved", "data": user}

else:

    return {"success": false, "message": "User not found", "data": []}


Bucles (for, while)

✅ Ejemplo Correcto:

even_numbers = [x for x in numbers if x % 2 == 0]


🚫 Ejemplo Incorrecto:

even_numbers = []

for x in numbers:

    if x % 2 == 0:

        even_numbers.append(x)

Directiva Técnica para Pruebas Controladas de Emisión de Comprobantes

Fecha: 24 / 11 / 2025
Dirigido a: Equipos de Desarrollo, QA, Soporte y Gestión
Emitido por: Área de Sistemas – Jefatura de Desarrollo

________________________________________________________________________________________________________________________________________________

  1. Objetivo
    Establecer los lineamientos obligatorios para la ejecución de pruebas relacionadas con la
    emisión de comprobantes electrónicos dentro de los entornos de QA / PRE-Producción /
    Producción Controlada, con el fin de evitar impactos contables, tributarios y operativos.

    _____________________________________________________________________________________________________________________________________

  2. Alcance
    La presente directiva aplica de manera estricta a todas las áreas internas y proveedores
    externos que realicen pruebas funcionales o técnicas dentro de los sistemas corporativos
    que generan comprobantes electrónicos (boletas o facturas).

    _____________________________________________________________________________________________________________________________________

  3. Lineamientos Obligatorios
    1. DNIs autorizados para pruebas de emisión de Boleta
      A partir de la fecha, únicamente se permite emitir BOLETAS de prueba usando los
      siguientes DNIs:
      • 75013406
      • 70503353
      • 71422696
      • 75527393
      • 71423703
        ________________________________________________________________________________________________________________________
    2. RUC autorizados para pruebas de emisión de Factura
      Solo se permite emitir FACTURAS de prueba utilizando los siguientes RUC:
      • 10750134063
      • 10705033531
      • 10714226962
        ________________________________________________________________________________________________________________________
    3. Obligación posterior a la emisión
      Todo comprobante emitido durante pruebas debe ser ANULADO, mediante:
      • Nota de crédito correspondiente, o
      • Anulación del comprobante según procedimiento interno.

        No se aceptará bajo ninguna circunstancia dejar comprobantes de prueba activos.
        ________________________________________________________________________________________________________________________
    4. Faltas y Sanciones
      El incumplimiento de esta directiva constituye falta grave.
      Se aplicarán las siguientes medidas:
      • Primera falta: Amonestación formal escrita.
      • Reiteración o incumplimiento crítico: Evaluación para suspensión o despido
        inmediato.
        ________________________________________________________________________________________________________________________
    5.  Vigencia
      Esta directiva entra en vigencia inmediata a partir de su comunicación.

Directiva Técnica para Pruebas Controladas de Emisión de Comprobantes

Directiva Técnica para Pruebas Controladas de Emisión de Comprobantes

Fecha: 24 / 11 / 2025
Dirigido a: Equipos de Desarrollo, QA, Soporte y Gestión
Emitido por: Área de Sistemas – Jefatura de Desarrollo

 

1. Objetivo

Establecer los lineamientos obligatorios para la ejecución de pruebas relacionadas con la emisión de comprobantes electrónicos dentro de los entornos de QA / PRE-Producción / Producción Controlada, con el fin de evitar impactos contables, tributarios y operativos.

2. Alcance

La presente directiva aplica de manera estricta a todas las áreas internas y proveedores externos que realicen pruebas funcionales o técnicas dentro de los sistemas corporativos que generan comprobantes electrónicos (boletas o facturas).

 

 

3. Lineamientos Obligatorios

3.1 DNIs autorizados para pruebas de emisión de Boleta

A partir de la fecha, únicamente se permite emitir BOLETAS de prueba usando los siguientes DNIs:

3.2 RUC autorizados para pruebas de emisión de Factura

Solo se permite emitir FACTURAS de prueba utilizando los siguientes RUC:

3.3 Obligación posterior a la emisión

Todo comprobante emitido durante pruebas debe ser ANULADO, mediante:

No se aceptará bajo ninguna circunstancia dejar comprobantes de prueba activos.

3.4 Rango Máximo de Monto Autorizado

Todo comprobante emitido durante pruebas deberá respetar el rango máximo de monto permitido, comprendido entre:

S/ 1.00 (un sol) como mínimo y S/ 50.00 (cincuenta soles) como máximo.

En caso sea estrictamente necesario exceder dicho monto, el responsable de la prueba deberá informar previamente y solicitar autorización expresa al Jefe de Programación.

 

 

4. Faltas y Sanciones

El incumplimiento de esta directiva constituye falta grave.

Como medida disciplinaria aplicará directamente:

 

 

5. Vigencia

Esta directiva entra en vigencia inmediata a partir de su comunicación.

Directiva para el uso de rutinas

Directiva Técnica para Control de Ejecución de CRONs mediante Token de Seguridad

Fecha: 01 / 12 / 2025
Dirigido a: Equipos de Desarrollo, QA, Soporte, Gestión y Operaciones
Emitido por: Área de Sistemas – Jefatura de Desarrollo

 

 

1. Objetivo

Establecer los lineamientos obligatorios para la ejecución de tareas programadas (CRONs) dentro de los sistemas corporativos, mediante el uso de un token de seguridad asociado a cada ruta. Esta medida tiene como finalidad prevenir la ejecución no autorizada, accesos indebidos, alteraciones en procesos operativos y riesgos de seguridad informática.

 

 

2. Alcance

La presente directiva aplica a todos los sistemas internos, servicios web, microservicios, módulos y proveedores externos que operen o interactúen con rutas HTTP utilizadas para la ejecución de CRONs en los entornos de QA, PRE-Producción y Producción.

 

 

3. Lineamientos Obligatorios

3.1 Uso obligatorio de Token

Toda ruta de CRON deberá utilizar el parámetro cron_token como mecanismo de autenticación obligatoria.
Ejemplo:

https://qawebservices.shalomcontrol.com/api/v1/cron/restriccion-clave-clientes?cron_token=.qaOverskull.


Ningún CRON podrá ejecutarse sin el token correspondiente.

 

 

3.2 Gestión del Token

El token será:

Cualquier divulgación indebida constituirá falta grave.

 

 

3.3 Validación del Token

Todo endpoint deberá validar el token antes de ejecutar la rutina.
En caso de token inválido o inexistente, el sistema deberá devolver:

HTTP 403 – Acceso Denegado

Queda prohibido exponer rutas sin protección o saltar la validación definida.

 

 

3.4 Solicitudes de Ejecución y Cambios

Toda solicitud relacionada con:

deberá ser comunicada previamente al Área de Programación, quienes autorizarán o rechazarán la intervención según los lineamientos internos.

No se permiten ejecuciones directas sin aprobación previa.

 

 

4. Faltas y Sanciones

El incumplimiento de esta directiva constituye falta grave.

Dependiendo del impacto técnico, de seguridad u operativo ocasionado, podrán aplicarse:

 

 

5. Vigencia

La presente directiva entra en vigencia de manera inmediata a partir de su comunicación y es de cumplimiento obligatorio para todas las áreas involucradas.

Documento Técnico

1.Introducción

Actualmente, el área de desarrollo recibe solicitudes de cambios, errores o mejoras a través de diversos canales sin una estructura estandarizada. Esto puede generar ambigüedades, retrasos en la planificación, errores en la implementación y retrabajo.

Con el objetivo de mejorar la eficiencia, trazabilidad y calidad del desarrollo, se propone formalizar el uso de tickets técnicos bajo una estructura determinada.

2.Objetivos

3.Propuesta de Estructura de Ticket Técnico 

Cada ticket deberá contener los siguientes puntos:

4.Encabezados

🔗 RUTAS

📖 CONTEXTO

🎯 DESCRIPCIÓN

⚙️ PRINCIPALES CASOS DE PRUEBA

📝 ANEXOS Y REFERENCIAS

Ejemplo: https://erp.overskull.com/app/task/TASK-2025-04209 

5.Prioridad

6.Complejidad

NIVEL

TIEMPO ESTIMADO

TIPO DE TAREAS

COMPLEJIDAD 1

0 - 30 m

Restricciones básicas

COMPLEJIDAD 2

30 m - 1 hr y 30 m

Restricción complejas (tarifas), Apis básicas

COMPLEJIDAD 3

1 hr y 30 m - 3 hr

Barridos, Apis complejos

COMPLEJIDAD 4

3 hr - 5 hr

Reportes, Optimizaciones, Nuevos módulos complejos

COMPLEJIDAD 5

> 5 hr

Integraciones