MADES. Convenio de codificación en HTML y CSS. Consejería de Hacienda y Administración Pública 06/03/2018

Transcripción

1 06/03/2018 Queda prohibido cualquier tipo de explotación y, en particular, la reproducción, distribución, comunicación pública y/o transformación, total o parcial, por cualquier medio, de este documento sin el previo consentimiento expreso y por escrito de la Consejería de Hacienda y Administración Pública de la Junta de Extremadura.

2 HOJA DE CONTROL Proyecto Documento Nombre del Fichero (Marco para el Desarrollo y Mantenimiento de los S.I.) -.odt Autor Versión/Edición 1.0 Fecha Versión 06/03/2018 Aprobado por Fecha Aprobación REGISTRO DE CAMBIOS Versión Causa del Cambio Responsable del Cambio Área Fecha del Cambio CONTROL DE DISTRIBUCIÓN Nombre y Apellidos Cargo Área Nº Copias Página 2 de 21

3 ÍNDICE 1 INTRODUCCIÓN Objetivo Alcance Ámbito de Responsabilidades Revisión de la Norma Publicación de la Norma GENERAL Reglas de Estilo General Reglas de Formato Generales Reglas Meta Generales HTML Reglas de Estilo HTML Reglas de Formato HTML Reglas de Estilo Reglas de Formato Formatting Rules Reglas Meta en...22 Página 3 de 21

4 1 INTRODUCCIÓN 1.1 Objetivo El objetivo del documento es definir las reglas de formato y estilo para los documentos HTML y. Su objetivo es el de mejorar la colaboración, la calidad del código y habilitar la infraestructura de apoyo. Se aplica a los ficheros de trabajo sin procesar que utilizan HTML y. 1.2 Alcance Todos los proyectos de desarrollo y mantenimiento de sistemas de información en tecnología web de la DGTIC. 1.3 Ámbito de Responsabilidades De aplicación a los proveedores y responsables de proyectos de sistemas de información de la DGTIC, así como por la unidad responsable de calidad que velará por su cumplimiento en cada sistema o aplicación. 1.4 Revisión de la Norma La norma que describe el Marco de Desarrollo de Sistemas de Información de la DGTIC, desarrollada en este documento será revisada de forma anual, para adaptar, corregir y ampliar en su caso tanto su alcance como su contenido. La unidad competente de la DGTIC será quien determine los responsables de la revisión, adaptación y modificación de la norma. 1.5 Publicación de la Norma El presente documento, así como las revisiones, serán de dominio público y se pondrá a disposición de cualquier ciudadano interesado utilizando los medios que la DGTIC estime oportunos, preferentemente a través de Internet, desde los portales de información que la Junta de Extremadura tiene de acceso público. Página 4 de 21

5 2 GENERAL 2.1 Reglas de Estilo General Protocolo Donde sea posible, se DEBERÍA usar el protocolo HTTPS para los recursos embebidos. Se DEBERÍA utilizar el protocolo HTTPS ( para las imágenes y otros ficheros multimedia, ficheros de hojas de estilo y ficheros de script, a menos que esos ficheros no estén disponibles sobre HTTPS. <!-- No recomendado: omite el protocolo --> <script src="//micdn.es/ajax/libs/jquery/3.1.0/jquery.min.js"></script> <!-- No recomendado: usa el protocolo HTTP --> <script src=" <script src=" /* No recomendado: omite el protocolo '//fonts.googleapis.com/css?family=open+sans'; /* No recomendado: usa el protocolo HTTP ' 2.2 Reglas de Formato Generales Sangría Se DEBE utilizar un sangrado de 4 espacios. NO DEBEN utilizarse tabulaciones ni mezclas entre tabulaciones y espacios. <ul> <li>fantastico Página 5 de 21

6 <li>increible </ul>.example { color: blue; Capitalización Se DEBEN utilizar siempre las minúsculas. Todo el código DEBE estar en minúsculas: Esto es aplicable a los nombres de elementos HTML, atributos, valores de atributos (al menos text/cdata), selectores, propiedades y valores de propiedades (con la excepción de cadenas de texto). <A HREF="/">Inicio</A> <img src="user.png" alt="usuario"> /* No recomendado */ color: #E5E5E5; color: #e5e5e5; Espacios en blanco sobrantes Los espacios en blanco al final de cada línea DEBEN eliminarse. Estos espacios no son necesarios y pueden complicar cualquier proceso de comparación entre ficheros. <p>usuario_ <p>nombre de usuario Página 6 de 21

7 2.3 Reglas Meta Generales Codificación DEBE utilizarse UTF-8 (no BOM) para codificar los ficheros HTML y. Hay que asegurarse de que el editor utiliza UTF-8 como codificación de caracteres por defecto, sin marca de orden de bytes. Se DEBE especificar la codificación en las plantillas y documentos HTML utilizando la etiqueta: <meta charset="utf-8"> NO se DEBE especificar la codificación en las hojas de estilo ya que éstas asumen que la codificación es UTF-8. Comentarios Se PUEDE explicar el código utilizando comentarios cuando sea necesario, donde sea posible, pero no hace falta hacerlo con el código que es evidente. Se asume que el mejor comentario es el que no existe. Si es imprescindible, se DEBE tener especial cuidado en que el contenido del comentario no se desfase con respecto al código comentado. Elementos de Acción Se PUEDEN marcar los elementos por hacer y las acciones con la etiqueta meta TODO. Se PUEDEN destacar los elementos por hacer solo con la palabra clave TODO, pero NO DEBE destacarse con ningún otro formato común Se PUEDE incluir un contacto (nombre de usuario o lista de correo) entre paréntesis con el formato TODO(contacto). Se PUEDEN incluir elementos de acción después de los dos puntos TODO: elemento de acción. Página 7 de 21

8 {# TODO(juan.diaz): revisar centrado # <center>test</center> <!-- TODO: eliminar etiquetas opcionales --> <ul> <li>manzanas</li> <li>naranjas</li> </ul> Página 8 de 21

9 3 HTML 3.1 Reglas de Estilo HTML Tipo de Documento Se DEBE utilizar HTML5 (sintaxis HTML). Todos los documentos HTML deben empezar con la etiqueta meta <!DOCTYPE html>. Los documentos HTML DEBEN utilizar un tipo MIME text/html. NO DEBE utilizarse nunca XHTML, application/xhtml+xml. NO DEBEN cerrarse los elementos vacíos, p.ej.: hay que usar <br> en lugar de <br>. HTML Válido DEBE utilizar HTML válido donde sea posible. Para validar el código, PUEDEN utilizarse herramientas como W3C HTML validator ( Utilizar HTML válido es un atributo básico de calidad, medible, que contribuye en el aprendizaje sobre los requerimientos y restricciones técnicas y que asegura un uso apropiado de HTML. <title>prueba</title> <article>esto es solo una prueba <!DOCTYPE html> <meta charset="utf-8"> <title>prueba</title> <article>esto es solo una prueba</article> Semántica DEBEN utilizarse los elementos HTML para la función para la que fueron creados. Por ejemplo, elementos de cabecera para las cabeceras, elementos p para los párrafos, Página 9 de 21

10 elementos a para los enlaces, etc. Usar HTML según su propósito es importante por razones de accesibilidad, reutilización y eficiencia del código. <div onclick="gotorecommendations();">todas las recomendaciones</div> <a href="recomendaciones/">todas las recomendaciones</a> Contenidos Alternativos DEBEN proporcionarse contenidos alternativos para los elementos multimedia. Para elementos tales como imágenes, videos, objetos animados vía canvas, hay que asegurarse de proporcionar un acceso alternativo. Para imágenes con significado, se DEBE utilizar texto alternativo (alt) y para elementos de video o audio se DEBE utilizar transcripciones y subtítulos, si están disponibles. Proporcionar contenidos alternativos es importante por razones de accesibilidad: Un usuario invidente tiene pocas evidencias para saber qué contiene una imagen sin un elemento alt, y otros usuarios pueden no tener forma de comprender lo que un audio o video intenta transmitir. NO DEBEN utilizarse atributos alt en imágenes cuando su contenido introduce redundancias o su propósito es puramente decorativo. <img src="hojadecalculo.png"> <img src="hojadecalculo.png" alt="captura de pantalla de una hoja de cálculo."> Separación de Responsabilidades DEBE separarse la estructura de la presentación y del comportamiento. DEBE mantenerse estrictamente separadas la estructura (marcado), la presentación (estilo) y el comportamiento (scripting) y DEBERÍA mantenerse la mínima interacción entre las tres. Es decir, hay que asegurarse de que los documentos y plantillas contienen HTML y solo HTML que solo sirven a propósitos únicamente estructurales. Hay que mover toda la presentación a hojas de estilo y todo el comportamiento a scripts. Además, hay que mantener un área de contacto lo más pequeña posible enlazando desde los documentos y las plantillas tan pocas hojas de estilo y pocos scripts como sea posible. Página 10 de 21

11 Separar la estructura de la presentación y el comportamiento es importante por razones de mantenimiento. Siempre es más costoso cambiar documentos y plantillas HTML que actualizar hojas de estilo y scripts. <!DOCTYPE html> <title>html no deseable</title> <link rel="stylesheet" href="base.css" media="screen"> <link rel="stylesheet" href="grid.css" media="screen"> <link rel="stylesheet" href="print.css" media="print"> <h1 style="font-size: 1em;">HTML no deseable</h1> <p>usar HTML sin separar responsabilidades <u>no es deseable</u> <center>puede provocar auténticos desastres de mantenimiento</center> <!DOCTYPE html> <title>mi primer rediseño de </title> <link rel="stylesheet" href="default.css"> <h1>mi primer rediseño de </h1> <p>separar responsabilidades es un ejercicio de responsabilidad <p> Es muy recomendable! Referencias de Entidad NO DEBEN utilizarse referencias de entidad. No existe la necesidad de usar referencias de entidad como,, o, asumiendo que se utiliza la misma codificación (UTF-8) para los ficheros, los editores de código y entre equipos de desarrolladores. La única excepción se aplica a los caracteres con un significado especial en HTML (como < y &) así como los caracteres de control o caracteres invisibles. El símbolo monetario para el Euro es &eur;. El símbolo monetario para el Euro es. Etiquetas Opcionales Se PUEDEN omitir las etiquetas opcionales (optional). Página 11 de 21

12 Para optimizar el tamaño de los ficheros y facilitar la exploración PUEDEN omitirse las etiquetas opcionales. La especificación de HTML5 ( define qué etiquetas pueden ser omitidas. <!DOCTYPE html> <html> <head> <title>gastando recursos</title> </head> <body> <p>ejemplo</p> </body> </html> <!DOCTYPE html> <title>optimizando recursos</title> <p>ejemplo Atributos type DEBEN omitirse los atributos type para las hojas de estilo y los scripts. No hay que utilizar este atributo para hojas de estilo a menos que no use y tampoco para scripts si no se va a usar Javascript. En estos contextos, no es necesario especificar el atributo type ya que HTML5 interpreta por defecto que son text/css y text/javascript. <link rel="stylesheet" href=" type="text/css"> <link rel="stylesheet" href=" <script src=" type="text/javascript"></script> <script src=" Página 12 de 21

13 3.2 Reglas de Formato HTML Formato General DEBE utilizarse una nueva línea para cada bloque, lista o tabla y sangrar cada elemento secundario. Hay que poner cada uno de estos elementos en una nueva línea independientemente del estilo de cada uno ( permite que los elementos asuman diferentes roles según la propiedad display). Si a su vez son elementos secundarios de un bloque, lista o tabla, habrá que incluir 2 espacios. <blockquote> <p><em>espacio</em>, la última frontera.</p> </blockquote> <ul> <li>el bueno <li>el feo <li>el malo </ul> <table> <thead> <tr> <th scope="col">income <th scope="col">taxes <tbody> <tr> <td>$ 5.00 <td>$ 4.50 </table> Comillas en HTML DEBEN utilizarse comillas dobles ("") para los valores de los atributos en lugar de comillas simples (''). <a class='btn btn-primary'>enviar</a> <a class="btn btn-primary">enviar</a> Página 13 de 21

14 4 4.1 Reglas de Estilo Válido DEBE usarse siempre un válido. Para comprobar la validez del contenido, hay que utilizar herramientas de validación, como el servicio de validación de la W3C ( Utilizar un válido es un atributo base de calidad medible que permite detectar código que no tiene ningún efecto, por lo que se puede eliminar y asegura un uso apropiado de. Nombre de Clase e ID DEBEN utilizarse nombres de clases e ID significativos o genéricos. En lugar de utilizar nombres crípticos o de presentación, hay que utilizar siempre nombres de ID y de clases que reflejen el propósito del elemento en cuestión, o que sean genéricos de alguna forma. Son preferibles los nombres que son específicos y reflejan el propósito del elemento debido a que son más comprensibles y menos probables de que cambien. Los nombres genéricos abarcan a aquellos elementos que no tienen un significado en particular o ninguno diferente de sus adyacentes o hermanos. Utilizar nombres funcionales o genéricos reduce la probabilidad de cambios innecesarios en documentos o plantillas. /* No recomendado: sin significado*/ #yee-1901 { /* No recomendado: de presentación */.button-green {.clear { /* Recomendado: específicos */ #gallery { #login {.video { /* Recomendado: genéricos */.aux {.alt { Página 14 de 21

15 Estilo de ID y Nombre de Clase DEBEN utilizarse nombres de ID y clases que sean tan cortos como sea posible y tan largos como sea necesario. Hay que intentar expresar qué es un ID o clase siendo lo más breve posible. Usando nombres de ID y clases de esta manera, se contribuye a conseguir niveles aceptables de comprensión y eficiencia del código. /* No recomendado */ #navigation {.atr { #nav {.author { Selectores de Tipo NO DEBERÍAN usarse nombres de ID y clases con selectores de tipo. Al menos que sea estrictamente necesario, no se deben utilizar nombres de elementos en conjunción con clases o ID. Por razones de rendimiento, es útil evitar el uso de selectores ancestrales. /* No recomendado */ ul#ejemplo { div.error { #ejemplo {.error { Propiedades Abreviadas DEBERÍAN utilizarse propiedades abreviadas donde sea posible. proporciona una gran variedad de propiedades abreviadas (como font) que deberían utilizarse donde sea posible, incluso en aquellos casos en los que utilice un único valor. El uso de las propiedades abreviadas es útil para la eficiencia del código y la comprensión. /* No recomendado */ Página 15 de 21

16 border-top-style: none; font-family: palatino, georgia, serif; font-size: 100%; line-height: 1.6; padding-bottom: 2em; padding-left: 1em; padding-right: 1em; padding-top: 0; border-top: 0; font: 100%/1.6 palatino, georgia, serif; padding: 0 1em 2em; Unidades con valor 0 DEBE omitirse la especificación de unidades después de atributos o propiedades con valor 0, excepto cuando sea estrictamente necesario. flex: 0px; /* Este componente requiere especificar la unidad. */ flex: 1 1 0px; /* No ambiguo sin la unidad, pero necesario en IE11. */ margin: 0; padding: 0; Ceros a la izquierda DEBERÍAN omitirse los ceros que se encuentren a la izquierda de valores. NO se DEBERÍAN poner ceros delante de aquellos valores que se encuentren entre -1 y 1. font-size:.8em; Notación Hexadecimal DEBERÍA utilizarse una notación hexadecimal de 3 caracteres donde sea posible. Es posible utilizar esta anotación para acortar los valores de color que lo permitan. /* No recomendado */ color: #eebbcc; Página 16 de 21

17 color: #ebc; Prefijos PUEDE incluirse un prefijo específico de aplicación en los selectores. En proyectos relativamente grandes, para código embebido en otros proyectos o sitios externos, se PUEDEN usar prefijos (como espacios de nombre) para los ID y los nombres de clase. Hay que utilizar identificadores cortos y únicos seguidos por un guión. Usar espacios de nombre previene la aparición de conflictos de nombres y hace el mantenimiento más fácil, por ejemplo para operaciones de búsqueda y reemplazo..adw-help { /* AdWords */ #maia-note { /* Maia */ Delimitadores de ID y Nombres de Clase DEBEN separarse las palabras de ID y nombres de clase con un guión. Para mejorar la comprensión y las búsquedas, NO DEBEN concatenarse palabras y abreviaturas en los selectores usando cualquier otro carácter que no sea un guión. /* No recomendado: no separar las palabras */.demoimage { /* No recomendado: usar guión bajo en lugar de guión medio */.error_status { #video-id {.ads-sample { 4.2 Reglas de Formato Formatting Rules Orden de Declaración DEBERÍAN ordenarse alfabéticamente las declaraciones para obtener un código consistente que sea fácil de recordar y mantener. DEBEN ignorarse los prefijos específicos de terceros para ordenar. Sin embargo, DEBERÍAN mantenerse ordenados aquellos prefijos múltiples, específicos de terceros, para una determinada propiedad (p.ej.: -moz va antes que -webkit). Página 17 de 21

18 background: fuchsia; border: 1px solid; -moz-border-radius: 4px; -webkit-border-radius: 4px; border-radius: 4px; color: black; text-align: center; text-indent: 2em; Sangría de Contenido en Bloque DEBE sangrarse todo el contenido en bloque, es decir, tanto las reglas dentro de las reglas como las declaraciones para reflejar la jerarquía y mejorar la screen, projection { html { background: #fff; color: #444; Fin de Declaración DEBE utilizarse un punto y coma después de cada declaración, por razones de consistencia y extensibilidad. /* No recomendado */.test { display: block; height: 100px.test { display: block; height: 100px; Página 18 de 21

19 Fin de Nombre de Propiedad DEBERÍA usarse un espacio a continuación de los dos puntos del nombre de una propiedad, pero NO DEBERÍA haber un espacio entre la propiedad y los dos puntos, por razones de consistencia. /* No recomendado */ h3 { font-weight:bold; h3 { font-weight: bold; Separación de Declaración de Bloques DEBERÍA utilizarse un espacio entre el último selector y la llave de apertura del bloque de declaración. La llave de apertura de declaración DEBERÍA estar en la misma línea que el selector en una regla dada. /* No recomendado: sin espacio */ #video{ margin-top: 1em; /* No recomendado: salto de línea innecesario */ #video { margin-top: 1em; #video { margin-top: 1em; Separación de Selector y Declaración DEBERÍAN separarse selectores y declaraciones en varias líneas, concretamente con una nueva línea por cada selector y declaración. Página 19 de 21

20 /* No recomendado */ a:focus, a:active { position: relative; top: 1px; h1, h2, h3 { font-weight: normal; line-height: 1.2; Separación de Reglas DEBERÍAN separarse las reglas con líneas en blanco. html { background: #fff; body { margin: auto; width: 50%; Comillas en DEBEN usarse comillas simples para los selectores de atributo y los valores de propiedad. NO DEBEN utilizarse comillas en los valores URI (url()). /* No recomendado url(" html { font-family: "open sans", arial, url( html { font-family: 'open sans', arial, sans-serif; Página 20 de 21

21 4.3 Reglas Meta en Sección Comentarios PUEDEN agruparse secciones de estilos con un comentario por sección. PUEDEN separarse cada sección con líneas en blanco. /* Header */ #adw-header { /* Footer */ #adw-footer { /* Gallery */.adw-gallery { Página 21 de 21