Share
I CSS 'verden er dokumentasjonen underutnyttet. Siden dokumentasjonen ikke er synlig for sluttbrukeren, blir dens verdi ofte oversett av klienter. Også, hvis det er første gangs dokumentasjonskode, kan det være vanskelig å bestemme hva å dokumentere og hvordan å gjøre det mest effektivt.
Men dokumentasjon av CSS kan gi mye til prosjektet ditt: fra å oppmuntre til bedre kodepraksis for å lette ombordingen av nye lagmedlemmer. I denne artikkelen vil jeg forklare fordelene ved å dokumentere CSS og dele hva teamet mitt og jeg på Bitovi anser å være de beste metodene for å gjøre dokumentasjon for deg - ikke omvendt. La oss dykke inn i det.
Det er vanskelig å komme på dokumentasjonsvognen når det ikke er klart for deg og teamet ditt hva du skal dokumentere eller hvordan du vil at den skal fungere. Så det første trinnet er å bli enige om hvilke konvensjoner du skal bruke og hvordan du skal implementere dem. Du kan gjøre dette i et live-dokument slik at alle i teamet kan bidra. På denne måten, når tilnærmingen din endres eller blir mer omfattende, kan du holde den oppdatert. En delt Google-doc, en wikiside på kodens repo eller (enda bedre) en side på din "Living Style Guide" er alle de beste stedene for dette.
La oss nå se på de faktiske "ground rules" som du kan inkludere.
Å forstå hvordan koden din er organisert gjør at noen kan hoppe rett inn i handlingen fra dag ett. En enkel måte å gjøre dette på er å lage et kart over filstrukturen der du kan forklare hva som er i det og hva som skal gå der. Vær spesielt oppmerksom på de stedene der det kan være tvetydighet når du gjør dette. For eksempel, som indikerer at filen "buttons.css" inneholder stiler for knapper, er ikke særlig nyttig, men indikerer at "tilpasset" katalogen er der tilpassede stiler for temaet er plassert, kan være en tidsbesparende.
Her er et eksempel:
Prosjektrute └── srs ├── styles // Basestiler. Stiler plassert her bør være tilgjengelige hvor som helst i programmet ├── bootstrap-custom // Tilpassede stiler som overskriver bootstrap ├── custom // Tilpassede stiler opprettet for programmet ├── demoer // Demoer for å illustrere stiler og interaksjoner for stilen guide ├── fonter ├── img // Bilder som brukes KUN i stilarkene ├── variabler // Variabler brukt i det egendefinerte temaet └── styles.less // Import av alle basestilsidene └─ - komponenter ├── varsler └── alert.less // Tilpassede stiler for varselkomponenten. Hver komponent har sitt eget stilark som gjør det mulig å tilpasse det spesielt for å forhindre oppblåsthet og stillekkasje.
Som en tommelfingerregel dokumentere de stedene hvor det er behov for avklaring. Ikke alle kataloger og filer trenger dokumentasjon (som i eksemplet ovenfor er "skrifter" selvforklarende). Sett deg selv i skoene til noen nye til prosjektet (eller husk de tider hvor du var den personen) og gi veiledningen du ønsker at du ville ha fått. Tanken er å gjøre dette på en måte som ikke er tidkrevende for deg, men er nyttig nok til å unngå gjentatte spørsmål.
Et annet viktig element for å peke ut her er hvor nye stiler skal legges til og hvilke trinn som skal følges. Eksemplet ovenfor demonstrerer dette, men det er verdt å angi det i detalj, med tanke på arveegenskapen til CSS.
For eksempel, i prosjekter der vi brukte Bootstrap som et underliggende rammeverk, har vi vanligvis tre steder der nye regler skal gå, avhengig av hva utvikleren prøver å oppnå. Så vi la til en veiledning til dokumentasjonen som består av tre scenarier:
Hvis du vil overskrive en stil som er definert av Bootstrap, så:
Hvis du vil legge til en ny stildefinisjon som ikke overskriver Bootstrap og Det bør være tilgjengelig hvor som helst i søknaden, da:
Hvis du vil legge til en ny stildefinisjon for en komponent (dette betyr at den bare vil være tilgjengelig for komponenten, uansett hvor komponenten brukes i programmet), så:
Denne veiledningen:
Kodningsstandardene dine eller CSS-stilguiden refererer til måten teamet ditt har avtalt på å skrive CSS. Dette inkluderer de beste metodene for å skrive kode, for eksempel formatering, navngiving og syntakskonvensjoner. Mange bedrifter har delt hvordan de gjør det (denne artikkelen fra CSS-Tricks har en flott samling: CSS Style Guides). Her er et par måter jeg synes er nyttig å dele denne typen informasjon:
Bruk dette formatet til å peke ut de tingene du vil unngå, samtidig som du gir et levedyktig alternativ. Dette fjerner tvetydighet og oppfordrer folk til å gjøre en bestemt ting. For eksempel:
| don'ts | Råd |
|---|---|
| Ikke bruk faner for innrykk. | Bruk fire (4) mellomrom for innrykk. |
| Ikke bruk under_scores eller "camelCase" for å navngi klasser eller IDer. | Bruk bindestreker til å skille ord. |
Ikke bruk Klasse- og ID-navn for å gjenspeile den underliggende oppmerkningsstrukturen. .container-span og .small-header-div er dårlige navn. | Tenk på CSS når det gjelder objekter og bruk enkle substantiver som navn. |
| Ikke bruk ID-er og altfor spesifikke valggivere til stil. Bruk bare disse når det er absolutt nødvendig (for eksempel skjermkontroller eller sideankre). | Bruk klasser for å forenkle gjenbrukbarhet og redusere CSS-selektorens spesifisitetskonflikter. |
Oppsummer retningslinjene dine i beste praksis og ta med eksempler. Dette vil gjøre hver enkelt lettere å lese og forstå. For eksempel:
| Beste praksis | Eksempel |
|---|---|
| Skriv flere valgorer på separate linjer. | .btn, .btn-link |
| Ta med ett mellomrom mellom velger og åpningsbrakett. | .selector |
| Bruk stenografi for hex-verdier når det er mulig. | #fff vs # ffffff |
| Skriv hex-verdier i små bokstaver. | # 3d3d3d vs # 3D3D3D |
| Legg inn nettadresser i enkelt anførselstegn. Vanligvis er enkelte anførselstegn foretrukket over dobbelt anførselstegn, siden de er lettere å skrive. | url ('/image.png') vs url ( "/Image.png") |
| Ikke bruk enheter for null (0) verdier, unntatt vinkler (deg) og tid (s eller ms). | margin-høyre: 0; vs margin-høyre: 0px; |
Måten en utvikler skriver kode kan i stor grad avvike fra en annen. Derfor er det viktig for teamet ditt å angi kodingsstandarder. Dette sikrer at kode er konsekvent i et prosjekt, noe som gjør det lettere å lese, skrive og gjennomgå. Men sørg for at alt du tar med i kodningsstandardene er en praksis som teamet ditt har avtalt om.
Jeg jobbet på et prosjekt der vi inkluderte dette i vår levende stilguide. Som en del av koden, har vi forpliktet og presset disse beste praksisene til repo. Så for å sikre at alle var ombord, måtte alle på laget godkjenne trekkforespørselen før vi kunne fusjonere den. Dette garanterte at alle måtte gjøre tid til å gjennomgå og diskutere det.
Når du bryter stilene dine inn i mindre og mer fokuserte stilark, er det enklere å dokumentere dem. Du kan også spare tid ved ikke å dokumentere hva som blir selvforklarende.
For eksempel, i stedet for å ha ett 800-linjers stilark med alle variablene du kan bruke i et tema, kan du ha en fil for hver av variablertypene. Dette vil spare tid ved å ikke måtte rulle opp og ned i filen som prøver å finne noe! Tenk også på tiden du kan lagre ved ikke å oppdatere indeksen hver gang du legger til eller gir nytt navn til en ny seksjon.
/ * ------------------------------------------- * \ variables.less Indeks - Fargepalett - Typografi - Knapper - Skjemaer - Oppsett - Meldinger og status - Generelt - Navigasjon - Karusell - Jumbotron \ * ------------------------ ------------------- * /
Et annet eksempel å vurdere når man arbeider i store applikasjoner, er den modulerte arbeidsflyten. Det forklarer hvorfor det å jobbe med mindre filer organisert av komponenter, gjør det enklere å teste og sette dem sammen i appen din.
En stor del av dokumentasjonen av CSS har riktig å gjøre med å skrive godt CSS og omvendt. Dette betyr at selv når tilstanden til CSS-kodebasen din kanskje ikke er den beste, kan håndhevende dokumentasjonsregler bevege deg mot et bedre system.
Dette er hvor dokumentasjon av CSS med en stilguide i tankene kommer på plass. Tanken bak den er at en stilguide kan hjelpe deg med å bestemme en god struktur for CSS fordi du må skille mellom:
Størstedelen av CSS-en din bør bestå av basislinjestilene, da de er tilgjengelige hvor som helst i applikasjonen, og påvirker alle elementene i standardstatus. Tilpassede stiler bør skje når du legger til komponenter med et bestemt utseende og atferd, eller i tilfeller hvor layoutet til et element eller en komponent på en side krever det.
En fin måte å fange opp hvordan dette bestemte oppsettet kan fungere i søknaden din, er å lage en stilguide-sitemap. Når du vet hvordan en stilguide ser ut i din søknad, kan du dokumentere elementer med det i tankene. Hvis du for eksempel har definert i stilguiden hvordan knapper og navigasjoner ser ut, er det klart kuttet hvor du skal legge til nye stiler og dokumentasjon for dem (i "buttons.css" og "navs.css"). Men hva med en navigasjon som er laget av knapper?
Å ha en stilguide kan hjelpe deg med å ta denne avgjørelsen, da du kan sammenligne hvordan knapper og navigasjoner ser ut, fra en skjerm og et oppslagsperspektiv. La oss se på dette eksemplet:
I dette tilfellet er det to mulige steder for CSS som vil definere navigasjonen gjort av knapper:
Accentsconagua
Når du har brutt ned stilarkene dine til mer håndterbare filer, kan du fortsette denne øvelsen ved å bryte ned hver stil i enkelte seksjoner.
Til å begynne med skal hver stilark i det minste inneholde en tittel og (når nyttig) en kort beskrivelse. Tittelen kan være så enkel som navnet på filen, aktivert for å se mer ut som en tittel (for eksempel: "Knapper" for stilarket "buttons.css"), eller det kan være det samme som navnet på filen, som dette:
/ ** * icons.css * / .icon font-family: 'bitovi'; snakk: ingen; font-style: normal; font-weight: normal; font variant: normal; tekst-transformasjon: ingen; linjehøyde: 1;
Jeg finner å bruke filnavnet spesielt nyttig når du feilsøker koden i nettleseren, og for det meste når filen er kompilert med andre filer, da jeg kan få en referanse til filen der stilen bor.
Vær også oppmerksom på at kommentastilen jeg brukte åpnet med / **vs bare / *. Dette er en konvensjon som brukes i JSDoc til å analysere kommentarer som skal inkluderes i den automatisk genererte dokumentasjonen. Jeg anbefaler at du bruker denne stilen, så mange generatorer av levende stilstyrer bruker JSDoc-formatet, så når du er klar til å bruke en generator, trenger koden din svært lite ekstra arbeid.
I alle fall kan du bruke andre stiler til å betegne en seksjon som:
/ * ------------------------------------------- * \ icons.css \*-------------------------------------------*/ .ikon font-familie: 'bitovi'; snakk: ingen; font-style: normal; font-weight: normal; font variant: normal; tekst-transformasjon: ingen; linjehøyde: 1;
I noen grad, dette avhenger av hva teamet ditt er enig i, er den beste måten å gjøre en seksjon skiller seg ut. Det eneste kravet er å bruke / * i begynnelsen og * / på slutten. Det som virkelig betyr noe er at hvilken tilnærming du bruker, holder deg til den og bruker den på tvers av CSS-koden din på en konsistent måte.
Hvis du mener at en beskrivelse kan være nyttig i et bestemt stilark, legger du det til som en del av denne første kommentaren. For eksempel:
/ ** * icons.css * * Ikoner skal formidle på en enkel og meningsfull måte konseptet av funksjonen * de representerer. Når du designer nye ikoner, må du fjerne eventuelle kompleksiteter * og følge det lineære og lette utseendet på ikonsettet. * / .icon font-family: 'bitovi'; snakk: ingen; font-style: normal; font-weight: normal; font variant: normal; tekst-transformasjon: ingen; linjehøyde: 1;
Å gjøre dette vil styrke ideen om at det er en del. Prøv også å bryte ned beskrivelsen i flere linjer (Harry Roberts anbefaler opptil 80 tegn) slik at det er lettere å lese mens du har flere filer åpne eller mens du leser det på Github.
Etter at du har lagt til en tittel og en beskrivelse, kan du gå et skritt videre ved å bryte ned stilene i stilarket i seksjoner. For å gjøre dette, tenk på hvordan logisk forklaring av innholdet i et stilark er fornuftig. For eksempel vil stilarket "buttons.css" vanligvis ha en seksjon der standardstilen på en knapp er definert ved bare å bruke klassen .btn. Deretter vil det være flere stiler som definerer forskjellige farger, størrelser og konfigurasjoner som kan brukes for å tilpasse utseendet og oppførselen ytterligere. Å lage seksjoner for hver av disse stilene vil gjøre det lettere å forstå og finne hvor nye klasser eller overskriv skal vises. Det er også mindre skremmende å se på en fil når koden er presentert i utdrag mot en lang fil hvor det er vanskelig å fortelle hvor stiler begynner og slutter.
La oss se på dette komparative eksempelet. Først en LESS kode blokk uten seksjoner:
.label-condensed-variant (@color) &: før bakgrunnsfargen: @color; .label border-radius: 0; font-family: @ font-family-bold; skriftstørrelse: 85%; stilling: relativ; & .label - kondensert font-size: @ font-size-xsmall; farge: @gray; bakgrunn: gjennomsiktig; polstring-høyre: @ polstring-liten; & .label - primær .label-kondensert variant (@ label-primary-bg); & .label - suksess .label-condensed-variant (@ label-success-bg); & .label - info .label-condensed-variant (@ label-info-bg); & .label-advarsel .label - kondensert variant (@ label-warning-bg); & .label - fare .label-condensed-variant (@ label-danger-bg); & .label - enkel font-family: @ font-family-base; skriftstørrelse: @ font-size-xsmall - 1; farge: @gray; grense: 1px solid @ grålys; polstring: 2px; grense-radius: @ grense-radius-liten; tekst-transformer: store bokstaver;
Og samme kodeblokk med seksjoner:
/ ** * bootstrap-custom / _labels.less Etiketter * * Overskriver standardstilene definert av bootstrap-rammeverket. * * / .label border-radius: 0; font-family: @ font-family-bold; skriftstørrelse: 85%; stilling: relativ; / ** * Kondenserte etiketter * * Endrer etiketter for å gi en mindre og smalere versjon med en farget sirkel som skal brukes i områder med lite plass (for eksempel i listevisninger). * / .label & .label - kondensert font-size: @ font-size-xsmall; farge: @gray; bakgrunn: gjennomsiktig; polstring-høyre: @ polstring-liten; / ** * Kondenserte etiketter - Farger * / .label-kondensert variant (@color) // Variant mixin for å sette sirkelfarge &: før bakgrunnsfarge: @color; .label & .label - kondensert & .label - primær .label-kondensert variant (@ label-primary-bg); & .label - suksess .label-condensed-variant (@ label-success-bg); & .label - info .label-condensed-variant (@ label-info-bg); & .label - advarsel .label-condensed-variant (@ label-warning-bg); & .label - fare .label-condensed-variant (@ label-danger-bg); / ** * Enkle etiketter * * Endrer etiketter for å gi en enkel lineær versjon der farger ikke brukes. * / .label & .label - enkel font-family: @ font-family-base; skriftstørrelse: @ font-size-xsmall - 1; farge: @gray; grense: 1px solid @ grålys; polstring: @ polstring-liten; grense-radius: @ grense-radius-liten; tekst-transformer: store bokstaver;
Dette er en fin måte å gi et øyeblikksbilde av hva som står i stilarket og et must i de prosjektene der, uansett grunn, lange stilark er der for å bli (ikke en fan av disse prosjektene, men de skjer!).
En stilarksindeks ser vanligvis ut som dette:
/ ** * icons.css * * Ikoner skal formidle på en enkel og meningsfull måte konseptet av funksjonen * de representerer. Når du designer nye ikoner, må du fjerne eventuelle kompleksiteter * og følge det lineære og lette utseendet på ikonsettet. * * Indeks * - Ikon Skrift * - Ikon Variasjoner * - Ikon Animasjoner * * /
Og selv om jeg elsker hvor ryddig og nyttig de kan være, må jeg innrømme at de lett kan glemmes, og derfor utdatert. De er også en smerte for å oppdatere når de er lange, og du bruker tall (så unngå dem!)
En alternativ måte å bruke indekser på er å la en stilguidegenerator gjøre jobben for deg ved å se på stilarkene dine, finne de seksjonene du har definert og generere en indeks for deg. Jeg vil utvide mer om dette emnet i slutten av denne artikkelen.
Her er hvor hemmeligheten med å dokumentere løgner. Det er lett å bli båret bort og gå inn i en dokumentasjonsfase en gang, for å glemme det og ende opp med bare en del av kodebasen din overdokumentert og resten ikke dokumenteres. Som med alt i livet, finner hemmeligheten balansen. Dokumentere de områdene der det er behov for oppmerksomhet fordi det er uforutsette avhengigheter, tilleggsressurser, eller viktige notater å ha i tankene. Det vil si at ikke hver eneste kode skal dokumenteres, men det er definitivt nyttig å bryte det ned i biter og forklare hva de brikkene er når det er nødvendig. På denne måten blir dokumentasjon et nyttig verktøy som er en del av arbeidsflyten din, og ikke en ettertanke som du unngår å gjøre. Men hvordan gjør du akkurat det? Her er et eksempel:
La oss si at du skal implementere markeringen og CSS for følgende kortkomponent:
Ser på designene du kan identifisere følgende stilmønstre:
Du kan deretter bryte ned CSS-implementeringen med disse mønstrene i tankene og bruke dokumentasjonen til å veilede deg. Til å begynne med kan stilarket "cards.css" inneholde en enkel intro som følger:
/ ** * cards.css * * Dette er stilene for kortkomponenten. * * Indeks * - Kortbase * - Kortgitter * - Kortliste * - Kort Mørk * /
Du kan inkludere mer nyttig informasjon i introduksjonen, men siden du bare er i gang, kan noe enkelt bidra til å legge dokumentasjonsskjelettet.
La oss da legge til delene hvor du skal jobbe med stilene dine i:
/ ** * cards.css * * Dette er stilene for kortkomponenten. * * Indeks * - Kortbase * - Kortgitter * - Kortliste * - Kort Mørk * / / ** * Kortbase * / / ** * Kortgitter * / / ** * Kortliste * / / ** * Kort Mørk * /
Med disse delene i tankene kan du visualisere hvordan koden skal struktureres. Du vet at du bør gjøre grunndefinisjonene på kortet fleksible og uavhengige nok til at du enkelt kan få kortet til å fungere i et rutenett, en liste eller en mørk versjon.
Så når du skriver koden, kan du få mer spesifikk med dine kommentarer:
/ ** * Kortbase * * Definerer utseendet og oppførelsen til standardkortet med hoveddelene: * - Kortbilde * - Kortinnhold * - Kortfotograf * / .kort ... .card__image ... .card__logo ... .card__content ... .card__footer ...
Jeg anser dette grunnleggende dokumentasjonsnivået du bør inkludere fordi det tjener som en veiledning for å sette opp koden og raskt informerer hvordan ting er organisert for den neste personen som jobber med den.
Neste nivå er å legge til kommentarer som er spesifikke for en regel, og som kan brukes til å forklare hva denne regelen gjør fordi den ikke er åpenbar med et blikk. For eksempel:
/ ** * Kortbase * * Definerer utseendet og oppførselen til standardkortet med flere deler: * - Kortbilde * - Kortlogo * - Kortinnhold * - Kortfotograf * / .kort @media (maks bredde: screen-xs) border: none; / * fordi kortet tar 100% av skjermen på mobilen * / .card__image ... .card__logo ... .card__content flex: 1 1 auto; / * "auto" må være eksplisitt for å unngå at div kollapser på IE. * /
Skjønnheten i denne tilnærmingen er at dokumentasjonen er der for å støtte og informere implementeringen mens du går, i motsetning til noe som legges til på et senere tidspunkt.
Her er noen flere eksempler på Bootstrap-rammen som viser når kommentarer er nyttige og når det er verdt å gå inn i mer detalj.
// Trenger nedfallsknapp siden: siste barn ikke gjelder, // gitt at en nedtrekksmeny brukes umiddelbart etter den .btn-gruppe> .btn: siste barn: ikke (første barn) , .btn-gruppe> .dropdown-toggle: ikke (: første barn) .border-venstre-radius (0);
Denne kommentaren forklarer hvorfor disse stilene eksisterer og hva de gjør. Det er også kort og til tross for å kommunisere ideen i et uformelt språk.
// Avkrysningsboks og radioalternativer // // For å støtte nettleserens skjema validering tilbakemelding, drevet av // 'påkrevd' attributt, må vi "skjule" inngangene via "klipp". Vi kan ikke bruke // 'display: none;' eller 'synlighet: skjult;' som det gjemmer også popover. // Bare visuelt gjemmer inngangene via 'opacity' ville la dem klikke i // visse tilfeller som er forhindret ved å bruke 'klipp' og 'peker-hendelser'. // På denne måten sikrer vi at et DOM-element er synlig for å plassere popover fra. // // Se https://github.com/twbs/bootstrap/pull/12794 og // https://github.com/twbs/bootstrap/pull/14559 for mer informasjon. [data-toggle = "buttons"] > .btn,> .btn-gruppe> .btn input [type = "radio"], skriv inn [type = "avkrysningsboks"] posisjon: absolutt; klips: rekt (0,0,0,0); peker-hendelser: ingen;
Dette er et godt eksempel på dokumentasjon som går mer i dybden, forklarer logikken bak en implementeringsbeslutning og gir lenker til ytterligere informasjon.
Med disse beste praksisene i tankene, er neste trinn å innlemme en levende stil guide som en del av dokumentasjonen din. En levende stilguide er et levende dokument som viser kommentarene du har tatt med i koden din, strukturert som et nettsted, slik at du kan navigere dokumentasjonen separat fra kildekoden.
Hva som gjør levende stil guider kraftige er at den faktiske dokumentasjonen lever med koden og kan enkelt oppdateres ettersom koden endres, slik at den kan forbli synkronisert og relevant. Den ekstra fordelen er at du kan gjøre denne dokumentasjonen tilgjengelig for andre personer i teamet ditt, som kanskje ikke interagerer direkte med koden (som designere, produktansvarlige eller QA-ingeniører). Disse gruppemedlemmene vil også finne det nyttig å vite hvordan brukergrensesnittet utformes.
I en levende stilguide kan du inkludere interaktive demonstrasjoner av koden din, og du kan videre organisere dokumentasjonen uavhengig av kodestrukturen.
Dokumentasjon av CSS begynner med klare regler og en godt strukturert kodebase. Når du er ferdig som en del av arbeidsflyten din, kan den også fungere som en veiledning for å strukturere koden din og holde den organisert som den vokser. Dette har den ekstra fordelen ved å gjøre det klart hvor ting er og hvor ny kode skal legges til, forenkle ombordstigning av nye medlemmer mens hurtigsporingsutvikling.
