Estándares de formato SQL – Mayúsculas y minúsculas, Sangría, Comentarios, Paréntesis

A nadie le gusta leer una pared de texto, incluso si es solamente texto plano. Cuando se trata de leer código, el problema es aún mayor. El código puede tener diferentes estilos de formato, lo cual puede hacer su trabajo o más fácil o más difícil. Puede hacer al código difícil de descifrar y entender. Un SQL limpio y ordenado es más rápido que un SQL inconsistentemente escrito; la revisión y resolución de problemas de SQL es más eficiente; los esfuerzos de desarrollo unidos son más efectivos; pasar proyectos de un equipo a otro es más fluido.

¿Cómo hacer su SQL legible de tal manera que sea suficiente sólo ver el código superficialmente para tener una idea general?

Es el formato de SQL lo que hace la diferencia.

La mejor solución es crear una guía de estilo personalizada para SQL. El problema, pero al mismo tiempo la ventaja que puede utilizar, es que no hay estándares de estilo ni formato, y es simplemente un asunto de preferencia. No hay un estilo de formato para SQL “mejor”, así que depende de usted y su equipo crear su propio conjunto de reglas de formato que serán aplicadas a todo el SQL en el que trabaje. Lo mejor que puede hacer por la legibilidad de su SQL es tener el equipo completo siempre aplicando el conjunto de estándares – de esa manera, todos se sentirán familiarizados con el formato usado en la compañía, y podrán leer rápidamente el código. Aquí hay algunas guías básicas que usted puede usar cuando configure las reglas de formato de SQL:

• Use comentarios para describir lo que hace SQL. Si usted está modificando un SQL existente, añada el nombre del autor, la fecha, describa las modificaciones y evite preguntas. No añada más de lo necesario y comente en lo obvio.
• Ponga cada sentencia SQL mayor en una nueva línea.
  

  USE Adventureworks2012;
  
  SELECT
           S.Businessentityid,
           E.Jobtitle
  FROM Sales.Salesperson
  WHERE S.Businessentityid > 10

• Ponga las palabras reservadas de SQL como SELECT y FROM, los nombres de funciones integradas como SUM, AVG, CASE y los tipos de datos como INT, CHAR, NTEXT en mayúsculas:
  

  CREATE TABLE Sales.Customer(
          Customerid INT IDENTITY(1, 1) NOT NULL,
          Personid INT NULL,
          Storeid INT NULL,
          Territoryid INT NULL,
          Modifieddate DATETIME NOT NULL,
          CONSTRAINT Pk_Customer_Customerid PRIMARY KEY 
          CLUSTERED(Customerid ASC)
              WITH(PAD_INDEX = OFF, 
              STATISTICS_NORECOMPUTE = OFF)ON [Primary])
  
  ON [Primary]

• Use CamelCase y no separe las partes de los nombres con guiones bajos: TableName, en lugar de Table_name, o use minúsculas y guiones bajos para separar partes de nombres: table_name
• Establezca abreviaciones estándar para objetos usados frecuentemente, como tbl para tables (tablas) o sp para stored procedures (procedimientos almacenados)
• Use comillas simples para caracteres, cadenas, binarios y Unicode –
• Establezca una regla para alias
• Use sangría para alinear líneas largas encapsuladas
• Use paréntesis en expresiones matemáticas complejas
• Sea consistente con la sangría – use o tab o espacio
• Do evite usar saltos de línea para mejorar la legibilidad
• Agrupación de Código – mantenga las líneas que ejecutan cierta tarea en bloques separados de código
• Limite el largo de las líneas – encapsule las líneas más largas que aproximadamente 80 caracteres

Y aquí está lo que usted debería evitar hacer:

• Sentencias profundamente anidadas
• EL uso de nombre ambiguos – sea consistente, use nombres simples y claros. Evite las excesivas abreviaciones
• Escribir un flujo de ejecución que es difícil de seguir

Una vez que las reglas están establecidas, usted necesita encontrar una manera fácil de aplicarlas. Aplicar manualmente todas las reglas es un proceso que consume tiempo donde es muy posible cometer errores.

Use nuestro SQL code formatter como una solución aquí.

ApexSQL Refactor es un add-in de SQL Server Management Studio y Visual Studio que formatea y refactoriza SQL utilizando cerca de 160 opciones de formato. Puede ser usado para distribuir y aplicar las reglas de formato SQL entre miembros de un equipo.

1. En el menú principal de SQL Server Management Studio y Visual Studio, haga clic en ApexSQL Refactor
2. Desde el menú ApexSQL Refactor, haga clic en la opción Format T-SQL code
3. Seleccione Formatting options
   

   

4. Establezca la opción específica como se describe en el artículo a continuación
5. Pre visualice el efecto de la opción en la consulta actual o un ejemplo integrado
   

   

6. En el menú de SQL Server Management Studio o Visual Studio, seleccione ApexSQL y seleccione ApexSQL Refactor. Haga clic en la opción Format T-SQL code y aplique el formato por defecto o personalizado para el código SQL en la ventana actual de la consulta

Mayúsculas y minúsculas

Antes de establecer los estándares de mayúsculas y minúsculas, asegúrese de que su base de datos no tiene colación sensitiva a mayúsculas y minúsculas, ya que esto puede causar grandes problemas cuando se está jugando con esta configuración. Usted debería establecer las reglas para:

• Palabras reservadas (por ejemplo, SELECT, DECLARE, CREATE, ALTER). Mayúsculas son recomendadas
• Tipos de datos (int, nvarchar, varchar)
• Nombres de objetos – identificadores (tabla, vista y nombres de procedimientos almacenados)
• Funciones integradas y de sistema (SUBSTRING, ABS, LEFT)
• Variables

Estilo 1 – Palabras reservadas, tipos e identificadores en minúsculas

create table humanresources.department(
             departmentid smallint identity(1, 1) not null,
             name dbo.Name not null,
             groupname dbo.Name not null,
             modifieddate datetime not null,
             constraint pk_department_departmentid 
primary key clustered(departmentid asc)
                 with(pad_index = off, allow_page_locks = on)on [primary])

on [primary];

Estilo 2 – Palabras reservadas en mayúsculas, tipos en minúsculas, identificadores según corresponda

CREATE TABLE Humanresources.Department(
             Departmentid smallint IDENTITY(1, 1) NOT NULL,
             Name dbo.Name NOT NULL,
             Groupname dbo.Name NOT NULL,
             Modifieddate datetime NOT NULL,
             CONSTRAINT Pk_Department_Departmentid 
PRIMARY KEY CLUSTERED(Departmentid ASC)
                 WITH(PAD_INDEX = OFF, ALLOW_PAGE_LOCKS = ON)ON [Primary])

ON [Primary];

Sangría

La sangría hace a SQL más fácil de seguir, ya que lo hace visualmente estructurado.

Es recomendado no usar sangría en una sentencia de múltiples líneas, de modo que sea claro dónde comienza la sentencia. Asegúrese de que el margen izquierdo de SQL tiene una sangría acorde al anidamiento de la sección.

Sea consistente con la sangría – establezca un número de espacios a usar para un toque a la tecla tab, o siempre use el mismo número de espacios. Usar tabulación en lugar de espacios es más fácil, dado que requiere menos clics, pero cuando usted comienza a cortar y pegar su SQL, los espacio son más fáciles de manejar.

Primero, establezca si usar espacios o tab para la sangría.

ApexSQL Refactor provee múltiples opciones para aritmética de sangría, operaciones lógicas y de comparación, sentencias de esquema, sentencias de datos y listas de columnas. Verifique las pestañas Expressions, Schema statements, Data statements, Joins, Value lists, Variables y Flow control para ver todas las opciones disponibles.

Estilo 1 – cada cláusula comienza en una nueva línea, ninguna tiene sangría

select s.businessentityid, e.jobtitle
from sales.salesperson as s
inner join humanresources.employee as e on e.businessentityid = 
s.businessentityid

Estilo 2 – cada cláusula y cada conjunto de argumentos comienzan en una línea separada. Cada sentencia subordinada a SELENCT también tiene sangría

SELECT
         S.Businessentityid, E.Jobtitle
  FROM
         Sales.Salesperson
        AS S
         INNER JOIN
         Humanresources.Employee
                       AS E
              ON E.Businessentityid = S.Businessentityid;

Estilo 3 – aplicar sangría a todas las listas de elementos igualitariamente junto a todos los nombres de columnas y tablas

SELECT
         S.Businessentityid,
         E.Jobtitle,
         S.Salesquota,
         S.Salesytd,
         S.Saleslastyear
  FROM
         Sales.Salesperson
         AS S
         INNER JOIN
         Humanresources.Employee
         AS E
         ON E.Businessentityid = S.Businessentityid;

Paréntesis

Los paréntesis pueden ser usados en diferentes contextos – en sentencias SELECT, parámetros de funciones, sentencias DDL, expresiones matemáticas, etc.

Los paréntesis de apertura en una expresión pueden ser colocados en una nueva línea y seguidos por un salto inmediato de línea. Los paréntesis de cierre pueden ser también colocados en una nueva línea, con o sin salto de línea después. Use cualquier cosa que haga a su código más legible:

Estilo 1 – sin saltos de línea después de paréntesis de apertura o cierre

CREATE TABLE Humanresources.Department (
        Departmentid SMALLINT IDENTITY ( 1, 1 )
                                   NOT NULL,
        Name dbo.Name NOT NULL,
        Groupname dbo.Name NOT NULL,
        Modifieddate DATETIME NOT NULL,
        CONSTRAINT Pk_Department_Departmentid 
        PRIMARY KEY CLUSTERED ( Departmentid ASC )
           WITH ( PAD_INDEX = OFF, 
           STATISTICS_NORECOMPUTE = OFF, 
           IGNORE_DUP_KEY = OFF, 
           ALLOW_ROW_LOCKS = ON, 
           ALLOW_PAGE_LOCKS = ON ) ON [Primary] )

ON [Primary];

Estilo 2 – un salto de línea después de los paréntesis de apertura

CREATE TABLE Humanresources.Department (
            Departmentid SMALLINT IDENTITY ( 1, 1 )
                                       NOT NULL,
            Name dbo.Name NOT NULL,
            Groupname dbo.Name NOT NULL,
            Modifieddate DATETIME NOT NULL,
            CONSTRAINT Pk_Department_Departmentid 
            PRIMARY KEY CLUSTERED ( Departmentid ASC )
               WITH ( PAD_INDEX = OFF, 
               STATISTICS_NORECOMPUTE = OFF, 
               IGNORE_DUP_KEY = OFF, 
               ALLOW_ROW_LOCKS = ON, 
               ALLOW_PAGE_LOCKS = ON ) 

    ON [Primary];

Estilo 3 – saltos de línea después de los paréntesis tanto de apertura como de cierre

CREATE TABLE Humanresources.Department
(
      Departmentid SMALLINT IDENTITY 
      ( 
            1, 1
      ) NOT NULL,
      Name dbo.Name NOT NULL,
      Groupname dbo.Name NOT NULL,
      Modifieddate DATETIME NOT NULL,
      CONSTRAINT Pk_Department_Departmentid 
      PRIMARY KEY CLUSTERED 
      ( 
            Departmentid ASC 
      )
      WITH 
      ( 
            PAD_INDEX = OFF, 
            STATISTICS_NORECOMPUTE = OFF, 
            IGNORE_DUP_KEY = OFF, 
            ALLOW_ROW_LOCKS = ON, 
            ALLOW_PAGE_LOCKS = ON
      )
) ON [Primary]

Comentarios

Los tipos de comentarios que pueden ser usados en SQL son:

• Comentarios de bloque /*…*/
• Comentarios en línea —

Aquí están un par de guías para comentarios que usted debería seguir:

• Escriba los comentarios clara y consistentemente
• No añada muchos comentarios
• Verifique si usted realmente necesita un nombre de desarrollador y una historia de revisiones

-- Select top sales agents
SELECT
         S.Businessentityid,
         E.Jobtitle,
         S.Salesquota,
         S.Salesytd,
         S.Saleslastyear
  FROM Sales.Salesperson
  WHERE S.Businessentityid > 10
  ORDER BY
         S.Salesquota;
/*add them to the bonus table*/

Usando ApexSQL Refactor, un tipo de comentario puede ser cambiado a otro

/* Select top sales agents*/
SELECT
      S.Businessentityid,
      E.Jobtitle,
      S.Salesquota,
      S.Salesytd,
      S.Saleslastyear
FROM Sales.Salesperson
WHERE S.Businessentityid > 10
ORDER BY
      S.Salesquota;
/*add them to the bonus table*/ 

Crear un estándar de formato SQL usualmente toma muchas pruebas y ajustes. Una vez que usted esté satisfecho con las reglas, grábelas a un perfil de formato y distribúyalas a todos los miembros del equipo.

1. En el diálogo Formatting options, haga clic en Export para grabar las reglas de formato a un archivo XML.
   

   

2. Especifique el nombre del archivo y su localización
3. Copie el archivo XML a la máquina de un compañero de trabajo
4. En el diálogo Formatting options, haga clic en Import
5. Navegue al archivo XML

Ahora sus colegas tendrán el mismo formato que usted.

Con SQL, su legibilidad es tan importante como que pueda ser ejecutado. Las guías claras de formato y la implementación automática de reglas de formato aseguran que todos los miembros del equipo y cualquier persona que herede el código pueda leerlo fácilmente. Use ApexSQL Refactor para implementar automáticamente todas las reglas de formato SQL.

Traductor: Daniel Calbimonte