Share
Nel mondo dei CSS, la documentazione è sottoutilizzata. Poiché la documentazione non è visibile all'utente finale, il suo valore viene spesso trascurato dai clienti. Inoltre, se è la prima volta che si documenta il codice, può essere difficile da determinare che cosa documentare e Come per farlo nel modo più efficace.
Tuttavia, la documentazione dei CSS può offrire molto al tuo progetto: dall'incoraggiare pratiche di codice migliori per facilitare l'inserimento dei nuovi membri del team. In questo articolo spiegherò i vantaggi della documentazione dei CSS e condividerò quello che io e il mio team di Bitovi consideriamo le migliori pratiche per far funzionare la documentazione per voi, non il contrario. Tuffiamoci dentro.
È difficile salire sul carro della documentazione quando non è chiaro a te e al tuo team cosa documentare o come si desidera che funzioni. Quindi il primo passo è quello di concordare quali convenzioni utilizzerai e come dovresti implementarle. Puoi farlo in un documento dal vivo in modo che tutti i membri del team possano contribuire. In questo modo, man mano che il tuo approccio cambia o diventa più completo, puoi tenerlo aggiornato. Un documento Google condiviso, una pagina wiki sul tuo repository di codice o (ancora meglio) una pagina sulla tua "guida di stile" sono tutti ottimi posti per questo.
Ora esaminiamo le "regole di base" che è possibile includere.
Capire come è organizzato il tuo codice permette a chiunque di saltare direttamente all'azione fin dal primo giorno. Un modo semplice per farlo è creare una mappa della struttura dei file in cui puoi spiegare cosa c'è dentro e cosa dovrebbe andare dove. Nel fare ciò, prestare particolare attenzione a quei luoghi in cui potrebbe esserci ambiguità. Ad esempio, indicando che il file "buttons.css" contiene stili per pulsanti non è molto utile, ma indica che la directory "personalizzata" è dove si trovano gli stili personalizzati per il tema può essere un risparmio di tempo.
Ecco un esempio:
Root del progetto └── srs ├── stili // Stili di base. Gli stili posizionati qui dovrebbero essere disponibili ovunque nell'applicazione ├── bootstrap-custom // Stili personalizzati che sovrascrivono bootstrap ├── custom // Stili personalizzati creati per l'applicazione ├── demos // Demo per illustrare stili e interazioni per lo stile guida ├── caratteri ├── img // Immagini utilizzate SOLO in fogli di stile ├── variabili // Variabili utilizzate nel tema personalizzato └── styles.less // Importazioni di tutti i fogli di stile di base └── componenti ├── avvisi └── alert.less // Stili personalizzati per il componente di avviso. Ogni componente ha il proprio foglio di stile che consente di personalizzarlo in modo specifico prevenendo la perdita di stile.
Come regola generale, documenta quei luoghi in cui è necessario un chiarimento. Non tutte le directory e file avranno bisogno di documentazione (come nell'esempio sopra "caratteri" è auto-esplicativo). Mettiti nei panni di qualcuno di nuovo nel progetto (o ricorda quelle volte in cui sei stato quella persona) e fornisci la guida che vorresti fosse stata data. L'idea è di farlo in un modo che non richiede tempo per te, ma è abbastanza utile per evitare domande ripetitive.
Un altro elemento chiave da sottolineare qui è dove devono essere aggiunti nuovi stili e tutti i passaggi che dovrebbero essere seguiti. L'esempio sopra lo dimostra, ma data la natura di ereditarietà del CSS, può essere utile specificarlo in dettaglio.
Ad esempio, nei progetti in cui abbiamo utilizzato Bootstrap come framework sottostante, di solito ci sono tre posti in cui dovrebbero andare le nuove regole, a seconda di ciò che lo sviluppatore sta cercando di ottenere. Quindi abbiamo aggiunto una guida alla documentazione che comprende tre scenari:
Se vuoi sovrascrivere uno stile definito da Bootstrap, allora:
Se si desidera aggiungere una nuova definizione di stile che non sovrascriva Bootstrap e che dovrebbe essere disponibile ovunque nell'applicazione, quindi:
Se si desidera aggiungere una nuova definizione di stile per un componente (questo significa che sarà disponibile solo per quel componente, ovunque il componente sia utilizzato nell'applicazione), quindi:
Questa guida:
I tuoi standard di codifica o guida allo stile CSS si riferiscono al modo in cui il tuo team ha concordato di scrivere CSS. Ciò include le migliori pratiche sulla scrittura di codice, come la formattazione, la denominazione e le convenzioni sulla sintassi. Molte aziende hanno condiviso il modo in cui lo fanno (questo articolo di CSS-Tricks ha una grande compilation: CSS Style Guides). Ecco un paio di modi in cui trovo utile condividere questo tipo di informazioni:
Usa questo formato per indicare le cose che vuoi evitare, fornendo al contempo un'alternativa valida. Ciò rimuove l'ambiguità e incoraggia le persone a fare una cosa specifica. Per esempio:
| cosa non fare | Cosa fare |
|---|---|
| Non utilizzare le schede per il rientro. | Usa quattro (4) spazi per il rientro. |
| Non utilizzare under_scores o "camelCase" per denominare classi o ID. | Usa i trattini per separare le parole. |
Non utilizzare nomi di classi e ID per riflettere la struttura di markup sottostante. .contenitore span e .piccolo-header-div sono brutti nomi. | Pensa ai CSS in termini di oggetti e usa nomi semplici come nomi. |
| Non utilizzare ID e selettori troppo specifici per lo stile. Utilizzali solo quando assolutamente necessario (ad esempio controlli del modulo o ancoraggi di pagina). | Utilizzare le classi per facilitare la riusabilità e ridurre i conflitti di specificità dei selettori CSS. |
Riassumi le tue linee guida nelle migliori pratiche e includi esempi. Questo renderà ognuno più facile da leggere e capire. Per esempio:
| Migliori pratiche | Esempio |
|---|---|
| Scrivi più selettori su linee separate. | .btn, .btn-link |
| Includere uno spazio tra il selettore e la parentesi graffa di apertura. | .selettore |
| Usa la scorciatoia per i valori esadecimali quando possibile. | #F F F vs #ffffff |
| Scrivi valori esadecimali in minuscolo. | # 3d3d3d vs # 3D3D3D |
| Racchiudi gli URL tra virgolette singole. Generalmente, le virgolette singole sono preferite rispetto alle virgolette doppie, dal momento che sono più facili da digitare. | url ('/image.png') vs url ( "/Image.png") |
| Non utilizzare unità per valori zero (0), ad eccezione di angoli (gradi) e tempo (s o ms). | margine-destra: 0; vs margin-right: 0px; |
Il modo in cui uno sviluppatore scrive codice può essere molto diverso da un altro. Questo è il motivo per cui è importante che il tuo team stabilisca standard di codifica. Ciò garantisce che il codice sia coerente in un progetto, il che rende più facile la lettura, la scrittura e la revisione. Ma assicurati che tutto ciò che includi nei tuoi standard di codifica sia una pratica concordata dal tuo team.
Ho lavorato a un progetto in cui abbiamo incluso questo nella nostra guida di stile di vita. Come parte del codice, abbiamo commesso e spinto queste best practice al repository. Quindi per assicurarsi che tutti fossero a bordo, tutti i membri del team hanno dovuto approvare la richiesta di pull prima di poterla unire. Ciò garantiva che tutti dovevano avere il tempo di esaminarlo e discuterne.
Quando rompi i tuoi stili in fogli di stile più piccoli e concentrati, è più facile documentarli. Puoi anche risparmiare tempo non dovendo documentare ciò che diventa auto-esplicativo.
Ad esempio, invece di avere un foglio di stile di 800 righe con tutte le variabili che è possibile utilizzare in un tema, è possibile avere un file per ciascuno dei tipi di variabile. Questo farà risparmiare tempo non dovendo scorrere su e giù nel file cercando di trovare qualcosa! Pensa anche al tempo che puoi risparmiare non dover aggiornare l'indice ogni volta che aggiungi o rinomina una nuova sezione.
/ * ------------------------------------------- * \ variables.less Indice - Tavolozza colori - Tipografia - Pulsanti - Moduli - Layout - Messaggi e stato - Generale - Navigazione - Carousel - Jumbotron \ * ------------------------ ------------------- * /
Un altro esempio da considerare quando si lavora in applicazioni di grandi dimensioni è il flusso di lavoro del modlet. Spiega perché lavorare con file più piccoli organizzati dai componenti consente di testarli e assemblarli più facilmente nella tua app.
Una buona parte della documentazione del CSS ha a che fare con la scrittura di buoni CSS e viceversa. Ciò significa che anche quando lo stato della tua base di codici CSS potrebbe non essere il migliore, l'applicazione delle regole della documentazione può spingerti verso un sistema migliore.
È qui che entra in gioco la documentazione dei CSS con una guida di stile. L'idea alla base è che una guida di stile può aiutarti a determinare una buona struttura per il tuo CSS, perché per crearne una dovrai distinguere tra:
La maggior parte del tuo CSS dovrebbe essere composta dagli stili di base, poiché sono disponibili ovunque nell'applicazione e influenzano tutti gli elementi nel loro stato predefinito. Gli stili personalizzati dovrebbero avere luogo quando si aggiungono componenti con un aspetto e un comportamento specifici o nei casi in cui il layout di un elemento o di un componente in una pagina lo richiede.
Un ottimo modo per catturare il modo in cui questa specifica configurazione può funzionare nella tua applicazione è creare una sitemap per la guida allo stile. Una volta che sai come appare una guida di stile nella tua applicazione, puoi documentare gli elementi con questo in mente. Ad esempio, se nella tua guida di stile hai definito come appaiono i pulsanti e le navigazioni, è chiaro dove aggiungere nuovi stili e documentazione per loro (in "buttons.css" e "navs.css"). Ma che dire di una navigazione fatta di pulsanti?
Avere una guida di stile può aiutarti a prendere questa decisione, dal momento che puoi confrontare il modo in cui i pulsanti e le navigazioni appaiono, da una prospettiva di visualizzazione e di revisione. Diamo un'occhiata a questo esempio:
In questo caso, ci sono due possibili posizioni per il CSS che definiranno la navigazione fatta di pulsanti:
Accentsconagua
Dopo aver suddiviso i tuoi fogli di stile in file più gestibili, puoi continuare questo esercizio suddividendo ogni stile in singole sezioni.
Per cominciare, ogni foglio di stile dovrebbe includere almeno un titolo e (quando utile) una breve descrizione. Il titolo potrebbe essere semplice come il nome del file, in maiuscolo per apparire più come un titolo (es: "Pulsanti" per il foglio di stile "buttons.css"), o potrebbe essere lo stesso del nome del file, come Questo:
/ ** * icons.css * / .icon font-family: 'bitovi'; parla: nessuno; stile font: normale; font-weight: normal; font-variant: normal; Trasformazione del testo: nessuno; altezza della linea: 1;
Trovo che usare il nome del file sia particolarmente utile quando eseguo il debug del codice nel browser, e soprattutto quando il file è stato compilato con altri file, poiché posso ottenere un riferimento al file in cui lo stile vive.
Inoltre, si noti che lo stile di commento che ho usato si apre con / **vs solo / *. Questa è una convenzione utilizzata in JSDoc per analizzare i commenti che dovrebbero essere inclusi nella documentazione generata automaticamente. Raccomando di usare questo stile, poiché molti generatori di guide in stile di vita usano il formato JSDoc, quindi quando sei pronto per usare un generatore, il tuo codice avrà bisogno di pochissimo lavoro aggiuntivo.
In ogni caso, puoi usare altri stili per denotare una sezione come:
/ * ------------------------------------------- * \ icons.css \*-------------------------------------------*/ .icona font-family: 'bitovi'; parla: nessuno; stile font: normale; font-weight: normal; font-variant: normal; Trasformazione del testo: nessuno; altezza della linea: 1;
In una certa misura, questo dipende da ciò che il tuo team è d'accordo è il modo migliore per far risaltare una sezione. L'unico requisito è usare / * all'inizio e * / alla fine. Ciò che conta davvero è che qualunque approccio tu usi, te lo rispetti e lo usi in tutto il tuo codice CSS in modo coerente.
Se pensi che una descrizione possa essere utile in un particolare foglio di stile, aggiungila come parte di questo primo commento. Per esempio:
/ ** * icons.css * * Le icone dovrebbero trasmettere in modo semplice e significativo il concetto della funzione * che rappresentano. Quando si progettano nuove icone, assicurarsi di rimuovere qualsiasi complessità * e seguire l'aspetto lineare e leggero dell'insieme di icone. * / .icon font-family: 'bitovi'; parla: nessuno; stile font: normale; font-weight: normal; font-variant: normal; Trasformazione del testo: nessuno; altezza della linea: 1;
Fare ciò rafforzerà l'idea che si tratti di una sezione. Inoltre, prova a suddividere la descrizione in più righe (Harry Roberts raccomanda fino a 80 caratteri) in modo che sia più facile da leggere mentre si hanno più file aperti o mentre lo si legge su Github.
Dopo aver aggiunto un titolo e una descrizione, puoi fare un ulteriore passo avanti scomposizione degli stili all'interno del foglio di stile in sezioni. Per fare ciò, pensa a come la spiegazione logica dei contenuti di un foglio di stile ha senso. Ad esempio, il foglio di stile "buttons.css" avrà in genere una sezione in cui viene definito lo stile predefinito di un pulsante applicando semplicemente la classe .btn. Quindi ci saranno stili aggiuntivi che definiscono colori, dimensioni e configurazioni diversi che possono essere applicati insieme per personalizzare ulteriormente l'aspetto e il comportamento. La creazione di sezioni per ciascuno di questi stili renderà più facile la comprensione e la ricerca di nuove classi o sovrascritture. Inoltre, è meno intimidatorio guardare un file quando il codice è presentato in frammenti rispetto a un file lungo in cui è difficile dire dove iniziano e finiscono gli stili.
Diamo un'occhiata a questo esempio comparativo. Innanzitutto, un blocco di codice MENO senza sezioni:
.label-condensed-variant (@color) &: before background-color: @color; .label border-radius: 0; famiglia di caratteri: @ font-family-bold; dimensione del carattere: 85%; posizione: relativa; & .label - condensed font-size: @ font-size-xsmall; colore: @gray; sfondo: trasparente; padding-right: @ padding-small; & .label - primary .label-condensed-variant (@ label-primary-bg); & .label - success .label-condensed-variant (@ label-success-bg); & .label - informazioni .label-condensed-variant (@ label-info-bg); & .label-warning .label - condensed-variant (@ label-warning-bg); & .label - danger .label-condensed-variant (@ label-danger-bg); & .label - simple font-family: @ font-family-base; font-size: @ font-size-xsmall - 1; colore: @gray; border: 1px solid @ gray-light; imbottitura: 2px; border-radius: @ border-radius-small; text-transform: maiuscolo;
E lo stesso blocco di codice con sezioni:
/ ** * bootstrap-custom / _labels.less Labels * * Sovrascrive gli stili predefiniti definiti dal framework bootstrap. * * / .label border-radius: 0; famiglia di caratteri: @ font-family-bold; dimensione del carattere: 85%; posizione: relativa; / ** * Etichette condensate * * Modifica le etichette per fornire una versione più piccola e più stretta con un cerchio colorato da utilizzare in aree con poco spazio (ad esempio nelle viste elenco). * / .label & .label - condensed font-size: @ font-size-xsmall; colore: @gray; sfondo: trasparente; padding-right: @ padding-small; / ** * Etichette condensate - Colori * / .label-condensed-variant (@color) // Variant mixin per impostare il colore del cerchio &: before background-color: @color; .label & .label - condensed & .label - primary .label-condensed-variant (@ label-primary-bg); & .label - success .label-condensed-variant (@ label-success-bg); & .label - informazioni .label-condensed-variant (@ label-info-bg); & .label - warning .label-condensed-variant (@ label-warning-bg); & .label - danger .label-condensed-variant (@ label-danger-bg); / ** * Etichette semplici * * Modifica le etichette per fornire una versione lineare semplice in cui i colori non vengono utilizzati. * / .label & .label - simple font-family: @ font-family-base; font-size: @ font-size-xsmall - 1; colore: @gray; border: 1px solid @ gray-light; padding: @ padding-small; border-radius: @ border-radius-small; text-transform: maiuscolo;
Questo è un ottimo modo per fornire un'istantanea di ciò che è nel foglio di stile e un must in quei progetti in cui, per qualsiasi motivo, ci sono lunghi fogli di stile (non un fan di quei progetti, ma succedono!).
In genere un indice di fogli di stile assomiglia a questo:
/ ** * icons.css * * Le icone dovrebbero trasmettere in modo semplice e significativo il concetto della funzione * che rappresentano. Quando si progettano nuove icone, assicurarsi di rimuovere qualsiasi complessità * e seguire l'aspetto lineare e leggero dell'insieme di icone. * * Indice * - Font di icone * - Variazioni di icone * - Animazioni di icone * * /
E anche se amo quanto possano essere puliti e utili, devo ammettere che possono essere facilmente dimenticati e quindi obsoleti. Sono anche dolorosi da aggiornare quando sono lunghi e stai usando numeri (quindi evita quelli!)
Un modo alternativo per utilizzare gli indici è lasciare che un generatore di guide di stile svolga il lavoro per te, esaminando i tuoi fogli di stile, individuando le sezioni che hai definito e generando un indice per te. Espanderò di più su questo argomento alla fine di questo articolo.
Qui è dove il segreto di documentare bugie. È facile essere portati via e andare in una frenesia della documentazione una volta, per poi dimenticarsene e finire con solo una parte della tua base di codice sovra-documentata e il resto non documentato. Come per tutto nella vita, il segreto è trovare l'equilibrio. Documenta quelle aree in cui è necessaria l'attenzione perché ci sono dipendenze impreviste, risorse addizionali, o note importanti avere in mente. Ciò significa che non tutti i bit del codice dovrebbero essere documentati, ma è sicuramente utile scomporlo in blocchi e spiegare cosa sono quei pezzi quando è necessario. In questo modo, la documentazione diventa uno strumento utile che fa parte del tuo flusso di lavoro e non un ripensamento che eviti di fare. Ma come lo fai esattamente? Ecco un esempio:
Diciamo che implementerai il markup e il CSS per il seguente componente della carta:
Guardando i disegni è possibile identificare i seguenti modelli di stile:
È quindi possibile suddividere l'implementazione CSS tenendo conto di tali modelli e utilizzare la documentazione per guidare l'utente. Per cominciare, il tuo foglio di stile "cards.css" può includere una semplice intro come segue:
/ ** * cards.css * * Questi sono gli stili per il componente della carta. * * Indice * - Base carta * - Griglia carta * - Lista schede * - Scheda scuro * /
Puoi includere più informazioni utili nell'introduzione, ma dal momento che hai appena iniziato qualcosa di semplice può aiutare a deporre lo scheletro della documentazione.
Quindi, aggiungiamo le sezioni in cui lavorerai i tuoi stili in:
/ ** * cards.css * * Questi sono gli stili per il componente della carta. * * Indice * - Base della carta * - Griglia della carta * - Lista delle carte * - Scheda scura * / / ** * Base della carta * / / ** * Griglia della carta * / / ** * Elenco delle carte * / / ** * Scheda Buio */
Con queste sezioni in mente, puoi visualizzare come dovrebbe essere strutturato il codice. Sai che dovresti rendere le definizioni di base della scheda flessibili e indipendenti abbastanza da poter facilmente far funzionare la scheda in una griglia, in una lista o in versioni scure.
Quindi mentre scrivi il codice, puoi ottenere informazioni più specifiche con i tuoi commenti:
/ ** * Base della carta * * Definisce l'aspetto e il comportamento della carta predefinita con le sue parti principali: * - Immagine della carta * - Contenuto della carta * - Piè di pagina della carta * / .card ... .card__image ... .card__logo ... .card__content ... .card__footer ...
Considero questo il livello base di documentazione che dovresti includere perché serve come guida per impaginare il codice e rapidamente informa come sono organizzate le cose per la prossima persona che ci lavora.
Il livello successivo è l'aggiunta di commenti specifici per una regola e che possono essere utilizzati per spiegare cosa sta facendo questa regola perché non è evidente a colpo d'occhio. Per esempio:
/ ** * Base carta * * Definisce l'aspetto e il comportamento della scheda predefinita con le sue parti multiple: * - Immagine scheda * - Logo scheda * - Contenuto scheda * - Piè di pagina scheda * / scheda grafica @media (larghezza massima: screen-xs) border: none; / * perché la scheda prende il 100% dello schermo su dispositivo mobile * / .card__image ... .card__logo ... .card__content flex: 1 1 auto; / * "auto" deve essere esplicito per evitare il div crollo su IE. * /
La bellezza di questo approccio è che la documentazione è lì per supportare e informare l'implementazione mentre si procede, rispetto a qualcosa che viene aggiunto in un secondo momento.
Qui ci sono un paio di altri esempi del framework Bootstrap che mostrano quando i commenti sono utili e quando vale la pena di andare più nel dettaglio.
// Need .dropdown-toggle since: last-child non si applica, // dato che un menu .dropdown viene usato immediatamente dopo itbtn-group> .btn: last-child: not (: first-child) , .btn-group> .dropdown-toggle: not (: first-child) .border-left-radius (0);
Questo commento chiarisce perché questi stili esistono e cosa stanno facendo. È anche breve e diretto, comunicando l'idea in un linguaggio casuale.
// Opzioni checkbox e radio // // Per supportare il feedback di validazione del modulo del browser, basato sull'attributo // 'required', dobbiamo "nascondere" gli input tramite 'clip'. Non possiamo usare // 'display: none;' o "visibilità: nascosta"; come quello nasconde anche il popover. // Nascondere semplicemente gli input tramite 'opacity' li lascerebbe cliccabili in / / in determinati casi che vengono prevenuti usando 'clip' e 'pointer-events'. // In questo modo, ci assicuriamo che un elemento DOM sia visibile per posizionare il popover. // // Vedere https://github.com/twbs/bootstrap/pull/12794 e // https://github.com/twbs/bootstrap/pull/14559 per ulteriori informazioni. [data-toggle = "buttons"] > .btn,> .btn-group> .btn input [type = "radio"], input [type = "checkbox"] position: absolute; clip: retto (0,0,0,0); pointer-events: none;
Questo è un ottimo esempio di documentazione che va più in profondità, spiegando la logica dietro una decisione di implementazione e fornendo collegamenti a informazioni aggiuntive.
Tenendo a mente queste buone pratiche, il passo successivo è incorporare a guida allo stile di vita come parte della tua documentazione. Una guida allo stile di vita è un documento vivente che mostra i commenti che hai incluso nel tuo codice strutturato come un sito web, così puoi navigare la documentazione separatamente dal codice sorgente.
Ciò che rende potenti le guide allo stile di vita è che la documentazione reale vive con il codice e può essere facilmente aggiornata man mano che il codice cambia, permettendogli di rimanere sincronizzato e pertinente. L'ulteriore vantaggio è che puoi rendere questa documentazione disponibile ad altre persone del tuo team che potrebbero non interagire direttamente con il codice (come designer, product manager o ingegneri di QA). Questi membri del team troverebbero anche utile sapere come si evolve l'interfaccia utente.
In una guida allo stile di vita, puoi includere dimostrazioni interattive del tuo codice e puoi ulteriormente organizzare la tua documentazione indipendentemente dalla struttura del codice.
La documentazione dei CSS inizia con regole chiare e una base di codice ben strutturata. Quando viene eseguito come parte del flusso di lavoro, può anche fungere da guida per strutturare il codice e organizzarlo man mano che cresce. Questo ha l'ulteriore vantaggio di chiarire dove sono le cose e dove dovrebbe essere aggiunto il nuovo codice, facilitando l'onboarding di nuovi membri durante lo sviluppo rapido del tracking.
