Share
În lumea CSS, documentația este insuficient utilizată. Întrucât documentația nu este vizibilă pentru utilizatorul final, valoarea sa este adesea neglijată de clienți. De asemenea, dacă este pentru prima oară documentarea codului, poate fi dificil de determinat ce pentru a documenta și Cum să o facă cel mai eficient.
Cu toate acestea, documentarea CSS poate oferi o mulțime proiectului dvs.: de la încurajarea unor practici de cod mai bune pentru a ușura îmbarcarea noilor membri ai echipei. In acest articol voi explica avantajele documentare CSS și împărtăși ce echipa mea și cu mine la Bitovi consider a fi cele mai bune practici pentru a face munca de documentare pentru tine-nu invers. Hai să ne aruncăm în ea.
Este greu să te duci la banda de documentare atunci când nu e clar pentru tine și echipa ta ce să documentezi sau cum vrei să funcționeze. Deci, primul pas este de a conveni asupra convențiilor pe care le veți folosi și asupra modului în care ar trebui să le implementați. Puteți face acest lucru într-un document live, astfel încât toată lumea din echipă să poată contribui. În acest fel, pe măsură ce abordarea dvs. se modifică sau devine mai cuprinzătoare, o puteți menține la zi. Un document Google comun, o pagină wiki în codul dvs. de repo sau (chiar mai bine) o pagină din "ghidul de stil de viață" sunt toate locuri excelente pentru aceasta.
Acum, să analizăm adevăratele "reguli de bază" pe care le puteți include.
Înțelegerea modului în care este organizat codul permite oricui să sară direct în acțiune din prima zi. O modalitate simplă de a face acest lucru este crearea unei hărți a structurii fișierelor în care puteți explica ce se află în ea și ce ar trebui să meargă acolo. Când faci asta, acordă o atenție deosebită acelor locuri unde ar putea exista ambiguități. De exemplu, ceea ce indică faptul că fișierul „buttons.css“ conține stiluri pentru butoane nu este foarte util, dar care indică faptul că directorul „personalizat“ este în cazul în care stilurile personalizate pentru tema sunt localizate poate fi un economizor de timp.
Iată un exemplu:
Rootul proiectului └────────────────────────────────────────────────────────────────────────────────────── Stiluri plasate aici ar trebui să fie disponibile oriunde în aplicația ├── bootstrap-personalizat // stiluri particularizate care se suprapun peste bootstrap ├── personalizate // Stiluri personalizate create pentru aplicația ├── demo-uri // Demo-uri pentru a ilustra stiluri și interacțiuni pentru stilul ghid ├── fonturi ├── img // Imaginile folosite numai în Variabile ├── variabile // foi de stil utilizate în temă personalizată └── styles.less // Importurile de toate foile de stil de bază └── componente ├── alerte └── alert.less // Stiluri personalizate pentru componenta de alertă. Fiecare componentă are o foaie de stil proprie, care permite personalizarea acesteia, împiedicând în special scurgerea de bloat și stil.
Ca regulă generală, documentați acele locuri unde este necesară clarificarea. Nu toate directorul și fișierul vor avea nevoie de documentație (ca în exemplul de mai sus "fonturi" este auto-explicativă). Puneți-vă în pantofi de cineva nou în proiect (sau amintiți-vă acele vremuri în care ați fost acea persoană) și oferiți îndrumările pe care doriți să vi le-ați fi dat. Ideea este să faceți acest lucru într-un mod care nu consumă mult timp pentru dvs., dar este suficient de util pentru a evita întrebările repetate.
Un alt element cheie care trebuie subliniat aici este locul în care trebuie adăugate stiluri noi și pașii care ar trebui urmați. Exemplul de mai sus demonstrează acest lucru, dar având în vedere caracterul de moștenire al CSS, poate fi util să se precizeze în detaliu.
De exemplu, în proiectele în care am folosit Bootstrap ca cadru de bază, avem în mod obișnuit trei locuri în care ar trebui să treacă noi reguli, în funcție de ceea ce dezvoltatorul încearcă să realizeze. Așa că am adăugat un ghid la documentația care cuprinde trei scenarii:
Dacă doriți să suprascrieți un stil definit de Bootstrap, atunci:
Dacă doriți să adăugați o nouă definiție de stil care nu suprascrie Bootstrap și care ar trebui să fie disponibil oriunde în aplicație, atunci:
Dacă doriți să adăugați o nouă definiție de stil pentru o componentă (aceasta înseamnă că va fi disponibilă numai acelei componente, indiferent de componenta utilizată în aplicație), atunci:
Acest ghid:
Standardele dvs. de codare sau ghidul de stil CSS se referă la modul în care echipa dvs. a convenit să scrie CSS. Acestea includ cele mai bune practici privind scrierea de coduri, cum ar fi formatele, denumirile și convențiile de sintaxă. Multe companii au împărtășit modul în care o fac (acest articol din CSS-Tricks are o mare compilație: CSS Style Guides). Iată câteva modalități prin care consider că este util să distribuiți acest tip de informații:
Utilizați acest format pentru a evidenția lucrurile pe care doriți să le evitați, oferind în același timp o alternativă viabilă. Aceasta elimină ambiguitatea și îi încurajează pe oameni să facă un lucru specific. De exemplu:
| Interdicții | Do |
|---|---|
| Nu utilizați filele pentru indentare. | Utilizați patru (4) spații pentru indentare. |
| Nu utilizați sub_score sau "camelCase" pentru a numi clase sau ID-uri. | Folosiți liniuțe pentru a separa cuvintele. |
Nu utilizați numele de clasă și de ID pentru a reflecta structura de marcaj subiacentă. .container-span și .-Header-div mici sunt nume proaste. | Gândiți-vă la CSS în termeni de obiecte și folosiți substanțe simple ca nume. |
| Nu utilizați ID-uri și selectori specifici pentru stil. Folosiți-le numai atunci când este absolut necesar (de exemplu, controale de formular sau ancore de pagină). | Utilizați clase pentru a facilita reutilizarea și pentru a reduce conflictele de specificitate ale selectorului CSS. |
Sintetizați liniile directoare în cele mai bune practici și includeți exemple. Acest lucru va facilita citirea și înțelegerea fiecăruia. De exemplu:
| Cele mai bune practici | Exemplu |
|---|---|
| Scrieți mai mulți selectori pe linii separate. | .BTN, .btn-link |
| Includeți un spațiu între selector și brațul de deschidere. | .selector |
| Utilizați scurtătură pentru valori hexazecimale când este posibil. | #fff vs #FFFFFF |
| Scrieți valori hexazecimal în litere mici. | # 3d3d3d vs # 3D3D3D |
| Includeți adrese URL în ghilimele simple. În general, citatele simple sunt preferate față de citatele duble, deoarece acestea sunt mai ușor de tipărit. | url ('/image.png') vs URL-ul ( "/Image.png") |
| Nu folosiți unități pentru valori zero (0), cu excepția unghiurilor (deg) și a timpului (s sau ms). | margin-dreapta: 0; vs margin-right: 0px; |
Modul în care un dezvoltator scrie cod poate diferi foarte mult de altul. De aceea, este important ca echipa dvs. să stabilească standarde de codificare. Acest lucru asigură faptul că codul este consecvent în cadrul unui proiect, ceea ce face mai ușor de citit, scris și revizuit. Dar asigurați-vă că tot ceea ce includeți în standardele de codare este o practică pe care echipa dvs. a convenit-o.
Am lucrat la un proiect în care am inclus acest lucru în ghidul nostru de viață. Ca parte a codului, am angajat și am împins cele mai bune practici la repo. Apoi, pentru a vă asigura că toată lumea se afla la bord, toată lumea din echipă trebuia să aprobe cererea de tragere înainte ca noi să o putem îmbina. Acest lucru garantează că toată lumea a trebuit să facă timp să revizuiască și să o discute.
Când spargeți stilurile în foi de stil mai mici și mai concentrate, este mai ușor să le documentați. Puteți, de asemenea, economisi timp fără a trebui să documentați ceea ce devine explicativ.
De exemplu, în loc să aveți o foaie de stil de 800 linii cu toate variabilele pe care le puteți utiliza într-o temă, puteți avea un fișier pentru fiecare dintre tipurile de variabile. Acest lucru va economisi timp prin faptul că nu trebuie să derulați în sus și în jos în fișier încercând să găsească ceva! Gândiți-vă la timpul pe care îl puteți salva prin faptul că nu trebuie să actualizați indexul de fiecare dată când adăugați sau redenumiți o secțiune nouă.
/ * ------------------------------------------- * \ variablesless Index - Color Palette - Typography - Butoane - Formulare - Aspect - Mesagerie & Status - General - navigaţie - Carusel - Jumbotron \ * ------------------------ ------------------- * /
Un alt exemplu de luat în considerare atunci când lucrăm în aplicații mari este fluxul de lucru de tip modlet. Aceasta explică de ce lucrul cu fișiere mai mici organizate de componente permite testarea și asamblarea acestora în aplicația dvs. mai ușor.
O mare parte din documentarea CSS are de a face cu scrierea unui CSS bun și invers. Acest lucru înseamnă că, chiar dacă starea bazei dvs. de cod CSS ar putea să nu fie cea mai bună, regulile de documentare aplicabile vă pot muta spre un sistem mai bun.
Aici se află documentarea CSS cu un ghid de stil în minte. Ideea din spatele ei este că un ghid de stil vă poate ajuta să determinați o structură bună pentru CSS-ul dvs., pentru a vă crea unul, va trebui să faceți distincția între:
Cea mai mare parte a CSS-ului dvs. ar trebui să fie formată din stilurile de bază, deoarece acestea sunt disponibile oriunde în aplicație și afectează toate elementele în starea lor implicită. Stilurile personalizate ar trebui să aibă loc atunci când adăugați componente cu aspect și comportament specific sau în cazurile în care aspectul unui element sau component dintr-o pagină o cere.
O modalitate excelentă de a capta modul în care această configurație specifică poate funcționa în aplicația dvs. este de a crea o hartă sitemap. Odată ce știți cum arată un ghid de stil în aplicația dvs., puteți documenta elemente cu acest lucru în minte. De exemplu, dacă ați definit în ghidul stilului modul în care arată butoanele și navigările, este clar să adăugați stiluri noi și documentație pentru ele (în "buttons.css" și "navs.css"). Dar o navigație făcută din butoane?
Având un ghid de stil vă poate ajuta să luați această decizie, deoarece puteți compara modul în care arată butoanele și navigările, dintr-o perspectivă de afișare și de marcare. Să ne uităm la acest exemplu:
În acest caz, există două locații posibile pentru CSS care vor defini navigarea prin butoane:
Accentsconagua
Odată ce ați defalcat foile de stil în fișiere mai ușor de gestionat, puteți continua acest exercițiu prin ruperea fiecărui stil în secțiuni individuale.
Pentru început, fiecare foaie de stil trebuie să includă cel puțin un titlu și (când este util) o scurtă descriere. Titlul ar putea fi la fel de simplu ca și numele fișierului, capitalizat pentru a arăta mai mult ca un titlu (ex: "Butoane" pentru foile de stil "buttons.css"), sau ar putea fi același cu numele fișierului, cum ar fi acest:
/ ** * icons.css * / .icon font-family: 'bitovi'; vorbesc: nici unul; font-style: normal; font-weight: normal; font-varianta: normal; text-transform: nici unul; linia-înălțime: 1;
Găsesc folosirea numelui de fișier deosebit de util atunci când depanează codul în browser și mai ales atunci când fișierul a fost compilat cu alte fișiere, deoarece pot obține o referință la fișierul în care trăiește stilul.
De asemenea, rețineți că stilul de comentariu pe care l-am folosit se deschide / **vs doar / *. Aceasta este o convenție folosită în JSDoc pentru a analiza comentariile care ar trebui incluse în documentația generată automat. Vă recomandăm să utilizați acest stil, deoarece multe generatoare de ghiduri de stil de viață utilizează formatul JSDoc, astfel încât atunci când sunteți gata să utilizați un generator, codul dvs. va necesita foarte puțină muncă suplimentară.
În orice caz, puteți utiliza alte stiluri pentru a indica o secțiune precum:
/ * ------------------------------------------- * \ icons.css \ * ------------------------------------------- * / .icon font-family: 'bitovi'; vorbesc: nici unul; font-style: normal; font-weight: normal; font-varianta: normal; text-transform: nici unul; linia-înălțime: 1;
Într-o anumită măsură, depinde de ceea ce echipa dvs. este de acord este cea mai bună modalitate de a face o secțiune să iasă în evidență. Singura cerință este de a utiliza / * la început și * / la sfarsit. Ceea ce contează cu adevărat este că, indiferent de abordarea pe care o utilizați, rămâneți la ea și folosiți-o în codul dvs. CSS într-un mod coerent.
Dacă credeți că o descriere ar putea fi utilă într-o anumită foaie de stil, atunci adăugați-o ca parte a acestui prim comentariu. De exemplu:
/ ** * icons.css * * Icoanele trebuie să transmită într-un mod simplu și semnificativ conceptul funcției pe care o reprezintă. Când proiectați noi pictograme, asigurați-vă că eliminați orice complexitate * și urmați aspectul linear și ușor al setului de pictograme. * / .icon font-family: 'bitovi'; vorbesc: nici unul; font-style: normal; font-weight: normal; font-varianta: normal; text-transform: nici unul; linia-înălțime: 1;
Acest lucru va întări ideea de a fi o secțiune. De asemenea, încercați să descompuneți descrierea în mai multe rânduri (Harry Roberts recomandă până la 80 de caractere), astfel încât să fie mai ușor de citit în timp ce aveți mai multe fișiere deschise sau în timp ce le citiți pe Github.
După adăugarea unui titlu și a unei descrieri, puteți merge mai departe, împărțind stilurile din foaia de stil în secțiuni. Pentru a face acest lucru, gândiți-vă cât de logic explică conținutul unei foi de stil are sens. De exemplu, foaia de stil "buttons.css" va avea în mod obișnuit o secțiune unde stilul implicit al unui buton este definit doar prin aplicarea clasei .BTN. Apoi vor exista stiluri suplimentare care definesc diferite culori, dimensiuni și configurații care pot fi aplicate în conjuncție pentru a personaliza în continuare aspectul și comportamentul său. Crearea de secțiuni pentru fiecare dintre aceste stiluri va face mai ușor să înțeleagă și să găsească unde ar trebui să apară clase noi sau suprascriere. De asemenea, este mai puțin intimidant să te uiți la un fișier atunci când codul este prezentat în fragmente, comparativ cu un fișier lung, unde este greu de spus unde încep și se termină stilurile.
Să examinăm acest exemplu comparativ. Mai întâi, un bloc de coduri mai mici fără secțiuni:
.etichetă-varianta condensată (@color) &: înainte de background-color: @color; .label raza de graniță: 0; font-family: @ font-family-bold; dimensiune font: 85%; poziție: relativă; & .label - condensat font-size: @ font-size-xsmall; culoare: @gray; fundal: transparent; padding-right: @ padding-small; & .label - varianta primară -lambă-condensată (@ label-primary-bg); & .label - succes .label-condensed-variant (@ label-success-bg); & .label - info .label-condensată-varianta (@ label-info-bg); & .label-avertisment .label - varianta condensată (@ label-warning-bg); & .label - pericol varianta -lambă-condensată (@ label-danger-bg); & .label - simplu font-family: @ font-family-base; font-size: @ font-size-xsmall-1; culoare: @gray; frontieră: 1px solid @ light-light; padding: 2px; raza de graniță: @ border-radius-small; text-transform: majuscule;
Și același bloc de cod cu secțiuni:
/ ** * bootstrap-custom / _labels.less Etichete * * Suprascrie stilurile implicite definite de framework-ul bootstrap. * * / .label raza de graniță: 0; font-family: @ font-family-bold; dimensiune font: 85%; poziție: relativă; / ** * Etichete condensate * * Modifică etichetele pentru a oferi o versiune mai mică și mai îngustă cu un cerc colorat pentru a fi utilizate în zone cu spațiu redus (de exemplu în vizualizările de listă). * / .label & .label - condensat font-size: @ font-size-xsmall; culoare: @gray; fundal: transparent; padding-right: @ padding-small; / ** * Etichete condensate - Culori * / varianta -labela-condensata (@color) // Varianta mixin pentru a seta culoarea cercului &: inainte de background-color: @color; .label & .label - condensată & .label - primar .label-condensată-varianta (@ label-primary-bg); & .label - succes .label-condensed-variant (@ label-success-bg); & .label - info .label-condensată-varianta (@ label-info-bg); & .label - avertizare .label-condensed-variant (@ label-warning-bg); & .label - pericol varianta -lambă-condensată (@ label-danger-bg); / ** * Simple Labels * * Modifică etichetele pentru a furniza o versiune liniară simplă în care culorile nu sunt utilizate. * / .label & .label - simplu font-family: @ font-family-base; font-size: @ font-size-xsmall-1; culoare: @gray; frontieră: 1px solid @ light-light; padding: @ padding-small; raza de graniță: @ border-radius-small; text-transform: majuscule;
Aceasta este o modalitate excelentă de a furniza o imagine a ceea ce este în foaia de stil și o necesitate în acele proiecte în care, din orice motiv, foi de stil lung sunt acolo pentru a rămâne (nu este un fan al acestor proiecte, dar ele se întâmplă!).
Un index de foi de stil se arată în felul următor:
/ ** * icons.css * * Icoanele trebuie să transmită într-un mod simplu și semnificativ conceptul funcției pe care o reprezintă. Când proiectați noi pictograme, asigurați-vă că eliminați orice complexitate * și urmați aspectul linear și ușor al setului de pictograme. * * Index * - Icon Font * - Variații de pictograme * - Icon Animații * * /
Și, deși îmi place cât de curată și folositoare pot fi, trebuie să recunosc că pot fi ușor uitați și, prin urmare, depășite. Ele sunt, de asemenea, o durere de actualizare atunci când acestea sunt lungi și utilizați cifre (evitați astfel!)
O modalitate alternativă de a utiliza indexurile este să lăsați un generator de stil să facă lucrul pentru dvs., uitându-vă la foile de stil, găsind secțiunile pe care le-ați definit și generând un index pentru dvs. Voi extinde mai mult pe acest subiect la sfârșitul acestui articol.
Iată unde se află secretul documentării. Este ușor să fii dus și să te duci într-o frenezie de documentare odată, să uiți de el și să ajungi doar cu o parte din codul tău deasupra documentării, iar restul fără documente. Ca și în tot ceea ce în viață, secretul este găsirea echilibrului. Documentați acele zone în care este nevoie de atenție deoarece există conexiuni neprevăzute, resurse aditionale, sau notite importante să aibă în minte. Asta înseamnă că nu orice cod de cod trebuie documentat, dar este cu siguranță util să-l descompuneți în bucăți și să explicați ce sunt acele bucăți atunci când este necesar. În acest fel, documentația devine un instrument util care face parte din fluxul dvs. de lucru și nu o gândire ulterioară pe care o evitați să o faceți. Dar cum faceți exact asta? Iată un exemplu:
Să presupunem că veți implementa marcajul și CSS pentru următoarea componentă a cardului:
Privind modelele, puteți identifica următoarele modele de stil:
Puteți apoi să descompuneți implementarea CSS cu aceste modele și să folosiți documentația pentru a vă ghida. Pentru început, fișa de stil "cards.css" poate include un simplu intro după cum urmează:
/ ** * cards.css * * Acestea sunt stilurile pentru componenta cardului. * * Index * - Baza Card * - Grilă Card * - Listă Card * - Card Dark * /
Puteți include mai multe informații utile în introducere, dar din moment ce începeți să începeți ceva simplu vă puteți ajuta să stabiliți scheletul de documentare.
Apoi, să adăugăm secțiunile în care veți lucra cu stilurile dvs. în:
/ ** * cards.css * * Acestea sunt stilurile pentru componenta cardului. * * Index * - Baza Card * - Grilă Card * - Listă Card * - Card Întuneric * / / ** * Bază Card * / / ** Grilă Card * / / ** * Listă Card * / / ** * Card Întuneric */
Având în vedere aceste secțiuni, puteți vizualiza modul în care ar trebui să fie structurat codul. Știți că ar trebui să faceți ca definițiile de bază ale cardului să fie flexibile și independente suficient încât să puteți face cu ușurință lucrul cu cartela într-o rețea, în listă sau în versiuni întunecate.
Atunci când scrieți codul, puteți obține mai multe detalii cu comentariile dvs.:
/ ** * Baza cardului * * Definește aspectul și comportamentul cardului implicit cu părțile principale: * - Imagine card * - Conținut card * - Footer card * / .card ... .card__image ... .card__logo ... .card__content ... .card__footer ...
Consider acest nivel de bază al documentației pe care ar trebui să-l includeți, deoarece servește ca un ghid pentru aranjarea codului și informează repede cum sunt organizate lucrurile pentru următoarea persoană care lucrează pe ea.
Următorul nivel adaugă comentarii care sunt specifice unei reguli și care poate fi utilizată pentru a explica ceea ce face această regulă, deoarece nu este evident dintr-o privire. De exemplu:
/ ** * Card Base * * Definește aspectul și comportamentul cardului implicit cu părțile sale multiple: * - Card Image * - Card Logo * - Conținut Card * - Card Footer * / .card @media (max- screen-xs) frontieră: niciuna; / * deoarece cardul ia 100% din ecran pe mobil * / .card__image ... .card__logo ... .card__content flex: 1 1 auto; / * "auto" trebuie să fie explicită pentru a evita div divizarea pe IE. * /
Frumusețea acestei abordări este că documentația este disponibilă pentru a susține și a informa implementarea în timp ce mergeți, față de ceva care este adăugat într-o perioadă ulterioară.
Iată câteva exemple suplimentare ale cadrului Bootstrap care arată când sunt utile comentariile și când merită să intri în detaliu.
// Nevoie .dropdown-toggle din moment ce: last-child nu se aplică, // dat fiind că un meniu derulant este utilizat imediat după .btn-group> .btn: last-child: not (: first-child) ; .btn-grup> .climbare-comutare: nu (: primul-copil) . border-left-radius (0);
Acest comentariu clarifică de ce există aceste stiluri și ce fac. Este, de asemenea, scurt și la punct, comunicând ideea într-un limbaj obișnuit.
// Opțiuni casetă de selectare și radio // // Pentru a susține feedback-ul validării formularului browserului, alimentat de atributul // 'necesar', trebuie să "ascundem" intrările prin intermediul "clipului". Nu putem folosi // 'display: none;' sau "vizibilitate: ascunsă"; deoarece ascunde și poporul. // Pur și simplu ascunderea vizuală a intrărilor prin "opacitate" le-ar lăsa clic clic în // anumite cazuri, care este împiedicată prin utilizarea "clip" și "pointer-events". // În acest fel, asigurăm că un element DOM este vizibil pentru a poziționa popoverul. // // Vezi https://github.com/twbs/bootstrap/pull/12794 și // https://github.com/twbs/bootstrap/pull/14559 pentru mai multe informații. [date-comutare = "butoane"] > .btn,> .btn-group> .btn introduceți [type = "radio"], introduceți [type = "checkbox"] position: absolute; clip: rect (0,0,0,0); pointer-events: nici unul;
Acesta este un exemplu excelent de documentare care merge mai profund, explicând logica din spatele unei decizii de punere în aplicare și furnizând linkuri către informații suplimentare.
Având în vedere aceste cele mai bune practici, următorul pas este de a include a ghid de stil de viață ca parte a documentației dumneavoastră. Un ghid de stil viu este un document viu care arată comentariile pe care le-ați inclus în codul dvs. structurat ca un site web, astfel încât să puteți naviga în documentație separat de codul sursă.
Ceea ce face că ghidurile stilului de viață sunt puternice este faptul că documentația actuală trăiește cu codul și poate fi ușor actualizată pe măsură ce codul dvs. se modifică, permițându-i să rămână în sincronizare și relevantă. Avantajul suplimentar este că puteți pune această documentație la dispoziția altor persoane din echipa dvs., care ar putea să nu interacționeze direct cu codul (cum ar fi proiectanții, managerii de produse sau inginerii QA). Acești membri ai echipei ar găsi, de asemenea, util să știe cum se modelează UI.
Într-un ghid de stil viu, puteți include demonstrații interactive ale codului dvs. și vă puteți organiza în continuare documentația independent de structura codului.
Documentarea CSS începe cu reguli clare și o bază de cod bine structurată. Când este făcută ca parte a fluxului dvs. de lucru, poate servi și ca un ghid pentru a vă structura codul și a-l păstra organizat pe măsură ce crește. Acest lucru are avantajul suplimentar de a clarifica unde sunt lucrurile și unde trebuie adăugat un nou cod, ușurând încasarea noilor membri în timp ce dezvoltarea rapidă.
