Guida al Codice di @mdo

Standard per sviluppare codice HTML e CSS flessibile, duraturo e sostenibile.

Indice dei contenuti

HTML

CSS

Regola d'oro

Imponi queste linee guida o altre stabilite da te in ogni momento. Piccolo o grande, fai notare ogni errore. Per aggiunte e contributi a questa Guida al Codice, sei pregato di aprire una segnalazione su GitHub.

Ogni linea di codice dovrebbe sembrare scritta da una sola persona, indipendentemente dal numero di contribuenti.

HTML

Sintassi

<!DOCTYPE html>
<html>
  <head>
    <title>Titolo della pagina</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Azienda">
    <h1 class="hello-world">Ciao, mondo!</h1>
  </body>
</html>

Doctype HTML5

Imponi la modalità standard e un rendering consistente in ogni browser possibile con questo semplice doctype all'inizio di ogni pagina HTML.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Attributo di lingua

Dalla specifica HTML5:

Gli autori sono incoraggiati a specificare un attributo lang nell'elemento html radice, fornendo la lingua del documento. Questo aiuta gli strumenti di sintesi vocale a determinare quali proununce usare, e così via.

Leggi di più sull'attributo lang nella specifica.

Vai su Sitepoint per una lista di codici lingua.

<html lang="it">
  <!-- ... -->
</html>

Modalità di compatibilità con Internet Explorer

Internet Explorer supporta l'uso di un <meta> tag di compatibilità per specificare quale versione di IE dovrebbe essere simulata per fare il rendering della pagina. A meno che le circostanze non richiedano altrimenti, è più utile istruire IE in modo che usi l'ultima modalità supportata in modalità edge.

Per maggiori informazioni leggi questo meraviglioso articolo su StackOverflow.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Codifica dei caratteri

Assicurati in maniera veloce e facile un rendering appropriato del contenuto dichiarando esplicitamente la codifica dei caratteri. Quando lo fai, puoi evitare di usare le entità carattere nel tuo HTML, a patto che la loro codifica sia la stessa del documento (di solito UTF-8).

<head>
  <meta charset="UTF-8">
</head>

Inclusioni CSS e JavaScript

Secondo la specifica HTML5, tipicamente non c'è bisogno di specificare l'attributo type quando includi file CSS e JavaScript, perché i valori di default sono rispettivamente text/css e text/javascript.

Link alla specifica HTML5

<!-- CSS esterno -->
<link rel="stylesheet" href="code-guide.css">

<!-- CSS interno al documento -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Praticità e purezza

Sforzati di mantenere gli standard e le semantiche HTML, ma senza sacrificare la praticità. Usa la minor quantità possibile di markup e complicazioni.

Ordine degli attributi

Gli attributi HTML dovrebbero essere in questo particolare ordine per una lettura più agevole del codice.

Le classi sono ottime per i componenti riutilizzabili, e dovrebbero essere le prime. Gli ID sono più specifici e dovrebbero essere usati con parsimonia (es. per i segnalibri interni alla pagina), dunque sono i secondi.

<a class="..." id="..." data-modal="toggle" href="#">
  Link di esempio
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Attributi booleani

Un attributo booleano è un attributo che non richiede alcun valore. L'XHTML richiedeva di dichiarare un valore, ma HTML5 non ha un simile requisito.

Per ulteriori letture, consulta la sezione WhatWG sugli attributi booleani:

La presenza di un attributo booleano su un elemento rappresenta il valore vero, e l'assenza dell'attributo rappresenta il valore falso.

Se devi includere il valore dell'attributo, e non serve che tu lo faccia, segui questa linea guida WhatWG:

Se l'attributo è presente, il suo valore dev'essere una stringa vuota o [...] il nome canonico dell'attributo, senza spazi all'inizio o alla fine.

In breve, non aggiungere alcun valore.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Ridurre il markup

Ogni qualvolta sia possibile, evita elementi genitori superflui quando scrivi HTML. Molte volte questo richiede iterazione e rifattorizzazione, ma produce meno HTML. Guarda il seguente esempio:

<!-- Non proprio bello -->
<span class="avatar">
  <img src="...">
</span>

<!-- Meglio -->
<img class="avatar" src="...">

Markup generato da JavaScript

Scrivere markup in un file JavaScript rende il contenuto più difficile da trovare, più difficile da modificare, e meno performante. Evitalo quando possibile.

CSS

Sintassi

Domande sui termini usati qui? Vedi la sezione sintassi dell'articolo Cascading Style Sheets su Wikipedia.

/* CSS cattivo */
.selettore, .selettore-secondario, .selettore[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* CSS buono */
.selettore,
.selettore-secondario,
.selettore[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Ordine delle dichiarazioni

Le dichiarazioni di proprietà collegate dovrebbero essere raggruppate seguendo l'ordine:

  1. Posizionamento
  2. Box model
  3. Tipografiche
  4. Visuali

Il posizionamento viene prima perché può rimuovere un elemento dal normale flusso del documento e sovrascrivere gli stili relativi al box model. Il box model viene dopo perché detta le dimensioni e la posizione di un componente.

Tutto il resto avviene dentro il componenente o senza influire sulle due sezioni precedenti, e dunque viene per ultimo.

Per una lista completa delle proprietà e del loro ordine, sei pregato di vedere Recess.

.declaration-order {
  /* Posizionamento */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Tipografia */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visuale */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Altro */
  opacity: 1;
}

Non usare @import

Rispetto ai <link>, @import è più lento, crea richieste aggiuntive, e può causare altri problemi non previsti. Evitali e invece opta per un approccio alternativo:

Per maggiori informazioni, leggi questo articolo di Steve Souders.

<!-- Usa elementi link -->
<link rel="stylesheet" href="core.css">

<!-- Evita gli @import -->
<style>
  @import url("more.css");
</style>

Posizionamento delle media query

Metti le media query il più vicino possibile ai set di regole rilevanti quando puoi farlo. Non raggrupparle tutte in un foglio di stile separato o alla fine del documento, o aumenterai le probabilità che chi legge il codice in futuro non le veda. Ecco una configurazione tipica.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Proprietà con prefissi

Quando usi proprietà con prefissi specifici, indenta ogni proprietà in modo che il valore della dichiarazione sia allineato verticlamente, per facilitare la modifica multilinea.

Con Textmate, usa Text → Edit Each Line in Selection (⌃⌘A). Con Sublime Text 2, usa Selection → Add Previous Line (⌃⇧↑) e Selection → Add Next Line (⌃⇧↓).

/* Proprietà con prefissi */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Dichiarazioni singole

In casi in cui un set di regole includa una sola dichiarazione, considera l'idea di rimuovere i ritorni a capo per aumentare la leggibilità e velocizzare la modifica. Qualunque set di regole con dichiarazioni multiple dovrebbe essere diviso in linee separate.

Il fattore chiave qui è la rilevazione degli errori: per esempio, un validatore CSS dice che hai un errore sulla Linea 183. Con una sola dichiarazione, non puoi mancarlo. Con dichiarazioni multiple, usare linee separate è d'obbligo se vuoi mantenere la sanità mentale.

/* Dichiarazioni singole su una linea */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Dichiarazioni multiple, una per linea */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Notazione abbreviata

Sforzati di limitare l'uso delle notazioni abbreviate ai casi in cui devi esplicitamente dichiarare tutti i valori disponibili. Tra le notazioni abbreviate comunamente abusate ci sono:

Spesso non dobbiamo impostare tutti i valori che una notazione abbreviata rappresenta. Per esempio, le intestazioni HTML impostando solo i margini superiori e inferiori, quindi quando necessario sovrascrivi solo quei due valori. Un uso eccessivo delle proprietà abbreviate genera spesso codice meno ordinato, con sovrascrizioni superflue ed effetti collaterali indesiderati.

Il Mozilla Developer Network ha un ottimo articolo sulle proprietà abbreviate per chi non è familiari con la notazione e il comportamento.

/* Cattivo esempio */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Buon esempio */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Annidamento con Less e Sass

Evita l'annidamento non necessario. Solo perché puoi annidare, non significa che debba farlo sempre. Considera l'annidamento solo se devi ridurre l'ambito di alcuni stili a un genitore e se ci sono elementi multipli da annidare.

// Senza annidamento
.table > thead > tr > th {  }
.table > thead > tr > td {  }

// Con annidamento
.table > thead > tr {
  > th {  }
  > td {  }
}

Commenti

Il codice è scritto e mantenuto da persone. Assicurati che il tuo codice sia descrittivo, ben commentato e approcciabile dagli altri. I commenti ottimi spiegano il contesto o lo scopo. Non limitarti a ripetere il componente o il nome della classe.

Assicurati di scrivere frasi complete per commenti più lunghi e frasi succinte per note generali.

/* Cattivo esempio */
/* Header modale */
.modal-header {
  ...
}

/* Buon esempio */
/* Elemento contenitore per .modal-title e .modal-close */
.modal-header {
  ...
}

Nomi delle classi

It's also useful to apply many of these same rules when creating Sass and Less variable names.

/* Cattivo esempio */
.t { ... }
.red { ... }
.header { ... }

/* Buon esempio */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selettori

Ulteriori letture:

/* Cattivo esempio */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Buon esempio */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organizzazione

/*
 * Intestazione sezione componenete
 */

.element { ... }


/*
 * Intestazione sezione componenete
 *
 * A volte devi inserire del contesto opzionale per l'intero componente. Fallo qui sopra se è abbastanza importante.
 */

.element { ... }

/* Sub-componenente contestuale o modificatore */
.element-heading { ... }

Preferenze dell'editor

Imposta il tuo editor ai seguenti settaggi per evitare inconsistenze comuni nel codice:

Considera l'idea di documentare e applicare queste preferenze nel file .editorconfig del tuo progetto. Per esempio, vedi quello di Bootstrap. Impara di più su EditorConfig.