Estándares de desarrollo en Salesforce

Introducción

¿Qué es este documento?

Esta Guía de Estándares de Desarrollo de Salesforce es el marco normativo oficial de Vantegrate para la construcción de soluciones en la plataforma Salesforce. Define las convenciones, patrones y mejores prácticas que garantizan un código consistente, mantenible y de alta calidad en todos los proyectos.

El documento establece reglas claras para la nomenclatura, la estructura del código, el modelo de datos, las automatizaciones, la seguridad y la documentación. Cada estándar está respaldado por ejemplos concretos, utilizando un caso real de implementación de facturación electrónica en Salesforce, para facilitar su comprensión y aplicación inmediata.

¿Para quién está diseñado?

Desarrolladores Salesforce: tanto nuevos integrantes del equipo de Vantegrate como desarrolladores experimentados encontrarán aquí las convenciones obligatorias para escribir código que se integre perfectamente con el resto del ecosistema de Vantegrate.

Arquitectos y Tech Leads: proporciona un marco de referencia para revisiones de código, decisiones de diseño y la evaluación de la calidad técnica.

Herramientas de IA Generativa: este documento está optimizado para ser consumido por asistentes de inteligencia artificial como Agentforce, Cursor, Claude y otras herramientas de generación de código.

¿Cómo usar este documento?

Para desarrolladores humanos

• Leer las secciones 1 y 2 completas antes de escribir cualquier código.
• Consultar la sección específica según el tipo de componente a desarrollar.
• Usar los checklists de la sección 11 antes de cada commit y deploy.
• Referirse al Apéndice A como guía rápida de nomenclatura.

Para herramientas de IA

• Incluir este documento (o secciones relevantes) en el contexto del prompt.
• Referenciar explícitamente las convenciones de nomenclatura de la sección 2.
• Solicitar que el código generado siga los patrones de las secciones 3-6.
• Validar el output contra las reglas PMD de la sección 8.

Principios de diseño del documento

1Principios Fundamentales

1.1 Regla Fundamental: Sólo Inglés

Principio: todo el código, los comentarios, los nombres de variables, métodos, clases, objetos, campos y la documentación técnica deben estar en inglés.

Razón: el inglés es el estándar de la industria, facilita la colaboración global, mejora la documentación y permite la integración con herramientas de análisis.

1.1.1 Distinción entre Label y API Name

Es importante distinguir entre Label (etiqueta visible al usuario) y API Name (nombre técnico en código):

• API Name: SIEMPRE en inglés, usando PascalCase. Es el identificador técnico utilizado en el código, las fórmulas, las integraciones y las automatizaciones.
• Label: PUEDE estar en español o en el idioma del usuario final. Es lo que el usuario ve en la interfaz de Salesforce.

1.2 Desarrollo Guiado por Pruebas (TDD)

El ciclo TDD es obligatorio para todo desarrollo Apex:

Requisitos de cobertura

1.3 Calidad y Performance

Reglas de oro (obligatorias):

• 🚫 NUNCA ejecutar SOQL dentro de loops.
• 🚫 NUNCA ejecutar DML dentro de loops.
• ✓ SIEMPRE usar bulk processing (diseñar para 200+ registros).
• ✓ SIEMPRE verificar Field Level Security (FLS).
• ✓ SIEMPRE verificar CRUD permissions antes de operaciones DML.
• ✓ SIEMPRE declarar sharing model (with sharing / without sharing).
• 📋 Cumplimiento obligatorio de reglas PMD críticas.

1.4 Principio de Solución Nativa

Priorizar siempre soluciones nativas de Salesforce en este orden:

2Nomenclatura Universal

Esta sección define las convenciones de nomenclatura obligatorias para todos los componentes de desarrollo en Salesforce.

2.1 Estilos de Case

2.1.1 Regla Crítica: PascalCase SIN guiones bajos internos

La convención Vantegrate exige PascalCase sin guiones bajos internos para los nombres de API de objetos y campos.

2.1.2 Uso de PascalCase

Aplicar a nombres que representan entidades, tipos o estructuras principales.

2.1.3 Uso de camelCase

Aplicar a variables, métodos, propiedades y elementos internos.

2.1.4 Uso de UPPER_SNAKE_CASE

Aplicar a constantes y valores inmutables.

2.1.5 Uso de kebab-case

Aplicar en referencias HTML y atributos web.

2.2 Tabla resumen: Case style por componente

2.3 Custom Objects

Case style: PascalCase. Formato API Name: [ObjectName]__c.

Reglas obligatorias

• USAR PascalCase para API Name.
• USAR Singular (Invoice__c, NO Invoices__c).
• USAR nombres descriptivos en inglés.
• Junction Objects: concatenar nombres en orden alfabético.
• NO usar abreviaturas excepto estándares (Id, URL, API).

2.4 Custom Fields

Case style: PascalCase sin guiones bajos internos. Formato API Name: [FieldName]__c.

2.5 Campos de Relación (Lookup y Master-Detail)

Los campos de relación requieren atención especial porque definen cómo los usuarios "leen" el modelo de datos.

2.5.1 Relación única hacia un objeto

Cuando un objeto tiene UNA sola relación hacia otro objeto, el API Name es simplemente el nombre del objeto destino:

1// Invoice__c tiene un lookup a Account
2Field API Name: Account__c
3Field Label:    Cuenta

2.5.2 Múltiples relaciones hacia el mismo objeto

Cuando un objeto tiene MÚLTIPLES relaciones hacia el mismo objeto, usar el patrón: [Rol][NombreDelObjeto]__c.

1// Invoice__c tiene dos lookups a Contact
2PrimaryContact__c → Label: Contacto Principal
3BillingContact__c → Label: Contacto de facturación

2.5.3 Ejemplos comunes de campos con rol

2.6 Junction Objects (Objetos de Unión)

Un Junction Object implementa una relación muchos-a-muchos entre dos objetos.

2.6.1 Nomenclatura

Regla fundamental: usar un nombre de negocio, NO un nombre técnico.

2.6.2 Estructura de un Junction Object

1Object: Application__c
2Label: Solicitud | Plural Label: Solicitudes
3
4Master-Detail fields:
5  - Candidate__c   (MD → Candidate__c)
6  - JobPosition__c (MD → JobPosition__c)
7
8Additional fields:
9  - ApplicationDate__c (Date)
10  - Status__c          (Picklist: Pending, Approved, Rejected)

2.6.3 Relación Master-Detail primaria

El primer campo Master-Detail creado se convierte en la relación primaria. Esto determina la herencia de la propiedad, el borrado en cascada y la disponibilidad de Roll-up Summary.

2.7 Record Types

DeveloperName: PascalCase, sin sufijo __c.
Patrón: [Objeto][Segmento] o [Objeto][Proceso].

2.8 Page Layouts

Patrón: [Objeto] Layout - [Variante].

2.9 Apex Classes

Case style: PascalCase con sufijo descriptivo según el rol.

2.10 Apex Methods y Variables

2.11 Triggers

Case style: PascalCase. Formato: [ObjectName]Trigger.

2.12 Test Classes y Methods

Test Class: PascalCase → [ClassBeingTested]Test.
Test Method: camelCase → test[Method]_[Scenario]_[Result].

2.13 Validation Rules

Formato: [Object]_[Field/Condition]_[RuleType].

2.14 Permission Sets

Permission Set: [Feature/Object]_[AccessLevel].
Permission Set Group: [Role]_Permissions.

2.15 Flows

API Name: PascalCase con underscores como separadores.
Variables: camelCase con prefijo de tipo.

2.16 Reports y Dashboards

Los nombres de Reportes y Dashboards son visibles para usuarios finales, por lo que priman la claridad y la organización.

2.16.1 Nomenclatura de Reports

Case style: Title Case con espacios (legible para usuarios).
Formato: [Área] – [Nombre Descriptivo] ([Período]).

2.16.2 Nomenclatura de Dashboards

Formato: [Área] – Dashboard [Propósito].

2.16.3 Nomenclatura de Carpetas

Formato: [Área/Departamento] – [Tema].

3Modelo de Datos

3.1 Campos de Integración Estándar

Para objetos que participan en integraciones con sistemas externos (como COMFIAR, ERPs, etc.):

4Estándares de Flow

Los Flows representan aproximadamente el 60% del desarrollo de automatización en Salesforce.

4.1 Variables de Flow

Case style: camelCase con prefijo de tipo (varB_, varT_, etc.).

4.2 Elementos de Flow

Decisiones

Case style: Sentence case (pregunta en inglés).

Asignaciones

Elementos de Datos

4.3 Manejo de Errores

4.4 Performance en Flows

Checklist de performance:

• Usar filtros específicos en elementos Get Records.
• Limitar registros retornados (usar LIMIT).
• Seleccionar solo campos necesarios.
• UN solo Get Records por objeto (consolidar).
• NUNCA DML dentro de loops — usar colecciones.
• SubFlows para lógica reutilizable.
• Máximo 50 elementos por Flow.
• Fault paths en elementos críticos.

5Desarrollo Apex y TDD

5.1 Estructura de Clases Apex

1/**
2 * @description Service class for Invoice-related business logic
3 * @author Vantegrate Development Team
4 * @date 2025-12-01
5 */
6public with sharing class InvoiceService {  // PascalCase
7
8    // UPPER_SNAKE_CASE for constants
9    private static final Decimal IVA_RATE = 0.21;
10    private static final Integer MAX_RETRY_COUNT = 3;
11
12    // camelCase for methods
13    public static Decimal calculateTotalWithTax(List<InvoiceLine__c> lines) {
14        // camelCase for variables
15        Decimal subtotal = 0;
16        Decimal taxAmount = 0;
17
18        for (InvoiceLine__c line : lines) {
19            subtotal += line.Amount__c;
20        }
21
22        taxAmount = subtotal * IVA_RATE;
23        return subtotal + taxAmount;
24    }
25}

5.2 Patrón Trigger Handler

El trigger debe ser mínimo y delegar toda la lógica al handler:

1// Trigger — PascalCase: [Object]Trigger
2trigger InvoiceTrigger on Invoice__c (before insert, after insert) {
3    new InvoiceTriggerHandler().run();
4}

1// Handler — PascalCase: [Object]TriggerHandler
2public class InvoiceTriggerHandler extends TriggerHandler {
3
4    public override void beforeInsert() {
5        InvoiceService.validateInvoices((List<Invoice__c>) Trigger.new);
6    }
7
8    public override void afterInsert() {
9        InvoiceService.sendToComfiar((List<Invoice__c>) Trigger.new);
10    }
11}

6Lightning Web Components (LWC)

6.1 Nomenclatura de Componentes

6.2 Mejores Prácticas LWC

• Usar @api para propiedades públicas expuestas a padres.
• Usar @track solo cuando sea necesario (objetos/arrays reactivos).
• Preferir getter methods sobre @track para valores computados.
• Manejar errores en wire methods.
• Usar ShowToastEvent para feedback al usuario.
• Evitar querySelector — usar data-id y template refs.
• Implementar loading states para operaciones async.
• Usar constantes UPPER_SNAKE_CASE para valores mágicos.

7Seguridad y Permisos

7.1 CRUD y FLS

En el siguiente ejemplo, con as user se aplican las verificaciones de forma automática y solo hay que interceptar la excepción:

1Account myAcc = new Account(
2    Name = 'Vantegrate Upgrade',
3    AnnualRevenue = 500000 // Supongamos que este campo es de solo lectura
4);
5try {
6    // Valida automáticamente CRUD, FLS y Sharing Rules
7    insert as user myAcc;
8} catch (DmlException e) {
9    // Manejo robusto de errores de seguridad
10    for (Integer i = 0; i < e.getNumDml(); i++) {
11        if (e.getDmlType(i) == StatusCode.INSUFFICIENT_ACCESS_OR_READONLY) {
12            System.debug('Error: El usuario no tiene permisos');
13        } else {
14            System.debug('Otro error de DML: ' + e.getDmlMessage(i));
15        }
16    }
17}

En el siguiente ejemplo, usando WITH USER_MODE al final de la query SOQL las verificaciones se hacen de forma automática y solo hay que interceptar la excepción:

1try {
2    // La consulta fallará si el usuario no tiene acceso a 'Phone' o 'Industry'
3    List<Account> accs = [
4        SELECT Id, Name, Phone
5        FROM Account
6        WHERE Industry = 'Technology'
7        WITH USER_MODE
8    ];
9    System.debug('Registros recuperados respetando seguridad: ' + accs.size());
10} catch (QueryException e) {
11    // El mensaje indicará qué campo o permiso falta
12    System.debug('Error de permisos en SOQL: ' + e.getMessage());
13}

7.2 Sharing Model

7.3 Checklist de Seguridad

• Declarar sharing model en todas las clases.
• Verificar CRUD antes de DML operations.
• Verificar FLS antes de acceder a campos sensibles.
• Usar WITH USER_MODE en queries.
• No hardcodear IDs.
• Sanitizar inputs de usuarios.
• Usar variable binding en SOQL (prevenir injection).
• Evitar información sensible en debug logs.

8Reglas PMD

8.1 Reglas Críticas (Bloquean Deploy)

8.2 Reglas de Mejores Prácticas

9Versionado y Release Management

9.1 Versionado Semántico

Formato: MAJOR.MINOR.PATCH.

9.2 Release Notes

Cada release debe documentar:

• Número de versión y fecha.
• Nuevas funcionalidades.
• Cambios en funcionalidad existente.
• Bug fixes.
• Breaking changes (si aplica).
• Pasos de migración (si aplica).
• Dependencias actualizadas.

10Documentación

10.1 ApexDoc para Clases

1/**
2 * @description Service for invoice lifecycle management and AFIP integration
3 * @author Vantegrate Development Team
4 * @date 2025-12-01
5 * @version 2.0
6 */
7public with sharing class InvoiceService {
8
9    /**
10     * @description Sends invoices to COMFIAR for AFIP authorization
11     * @param invoices List of invoices to process
12     * @return ProcessingResult Results including CAE numbers
13     * @throws IntegrationException When COMFIAR is unavailable
14     * @example
15     * List<Invoice__c> invoices = [SELECT Id FROM Invoice__c];
16     * InvoiceService.sendToComfiar(invoices);
17     */
18    public static ProcessingResult sendToComfiar(List<Invoice__c> invoices) {
19        // Implementation
20    }
21}

10.2 Documentación de Flows

Cada Flow debe incluir en Description:

1FLOW NAME: Invoice Authorization Automation
2
3PURPOSE:
4Sends new invoices to COMFIAR for AFIP authorization
5and updates CAE information upon response.
6
7TRIGGER:
8Record-Triggered Flow on Invoice__c (After Insert)
9
10INPUT REQUIREMENTS:
11- Invoice with Customer, InvoiceDate, and at least one Line
12
13ERROR HANDLING:
14- Validation errors: Set ProcessingStatus__c = 'Error'
15- COMFIAR errors: Log to IntegrationLog__c, alert admin
16
17VERSION: 2.0
18LAST MODIFIED: 2025-12-01
19AUTHOR: Vantegrate Development Team

11Checklists y Templates

11.1 Checklist Pre-Deployment

• Todas las clases tienen cobertura ≥ 75%.
• Todos los tests tienen assertions significativas.
• PMD no reporta violaciones críticas.
• ApexDoc completo en clases públicas.
• Flows tienen fault paths en elementos críticos.
• No hay SOQL/DML en loops.
• Bulk testing completado (200+ records).
• Nombres siguen convenciones del estándar.
• Security Review: CRUD/FLS verificado.
• Release notes documentadas.

11.2 Checklist Code Review

• Código en inglés (variables, métodos, comentarios).
• Nomenclatura correcta según estándar.
• Triggers delegan a Handlers.
• Classes declaran sharing model.
• No hay IDs hardcodeados.
• Error handling implementado.
• Logging apropiado con LoggingLevel.
• Tests cubren escenarios positivos y negativos.
• Bulk processing implementado.

11.3 Checklist Nuevo Custom Object

• API Name en PascalCase y singular.
• Label y Plural Label definidos.
• Description completada.
• Campo ExternalId__c creado.
• Campo IsActive__c creado.
• Campo SourceSystem__c creado.
• Campo LastProcessedDateTime__c creado.
• Campo ProcessingStatus__c creado.
• Sharing model configurado.
• Permission Sets actualizados.
• Page Layouts configurados.

AApéndice A: Tabla de Referencia Rápida de Nomenclatura