Generella och gemensamma principer
För att underlätta utvecklingen av Vetenskapsrådets webbplatser över tid är det viktigt att hålla sig till några generella principer.
Principerna syftar till att skapa enklare, lättförståelig och hållbar kod som är lätt att underhålla och vidareutveckla.
Utveckling av mallar
Mallar bör byggas med CMS-systemets eget system för responsiv design, utan användning av extra ramverk för responsivitet.
Mallar i Sitevision
Skapa innehållsytor i Sitevision så redaktören kan skapa innehåll utan att lägga in ytterligare grid eller layouter. Innehållsytor ska vara tomma eller endast innehålla rubrik, ingress och brödtext. Innehållsytor ska vara tomma eller endast innehålla rubrik, ingress och brödtext, och bör inte innehålla delar som är en del av utseendet, såsom grid, gridrader och layouter.
Utveckla enkelt och undvik risker
När vi utvecklar ska vi sträva efter att skapa enkla och förklarande lösningar. Koden bör struktureras i mindre logiska delar för att göra den enklare att förstå och underhålla. Nästlade if-satser och loopar bör undvikas, och istället bör kodstycken delas upp i funktioner som förklarar syftet. Det är även viktigt att undvika beroenden till andra komponenter. Saknas beroenden mellan komponenter kan koden leva längre utan underhåll och uppdateras/ersättas utan att påverka andra delar.
Koda flexibelt och undvik hårdkodade URL:er eller ID-nummer, och ta höjd för kommande förändringar. Att sidor kan byta namn, flyttas eller mer funktioner ska in behöver vi kunna hantera. Det kan innebära att du samlar värden som kan förändras på en plats.
Ge nästa utvecklare en bra start
En beskrivning av utvecklingen (readme.md fil) bör skapas och underhållas för att underlätta för nästa utvecklare att ta över arbetet. Det är även viktigt att skriva beskrivningen redan i planeringsstadiet och lägga filen där systemfilerna ligger så att den följer med till nästa utvecklare.
Namngivningsregler
Alla webbplatser har ett eget prefix i CSS. Prefixet är oftast de 2-3 första bokstäverna i webbplatsens namn eller en förkortning av namnet. Prefixet är unikt för webbplatsen och underlätta vid felsökning och separerar vår kod från systemets kod. Ta för vana att sätta prefixet först i filnamn och som utvecklats för webbplaten, samt webbplatsens CSS-klasser.
Namn på filer
Alla filer namnges med kabab-case efter inledande prefix. Filnamnet ska vara beskrivande och förklara vad funktionen gör.
Exempel
vrd-startpage-hero-logic.js
vrd-startpage-hero-style.css
vrd-startpage-hero-frontend-templet.vm
Namngivning i utvecklingsspråk
För att göra källkoden lättförståelig och enhetlig i all utveckling använder vi engelska för variabler, funktioner, kommentarer och annat. Därför har vi utarbetat namngivningsregler för olika programmeringsspråk som vi använder oss av.
I JavaScript och Velocity använder vi CamelCase, där varje ord i variabel- eller funktionsnamnet skrivs med versaler utom första ordet. Exempel: firstName, calculateTotalPrice.
| Språk | Namngivning |
|---|---|
| JavaScript | camelCase |
| VM | camelCase |
| CSS | kebab-case |
Variabler och funktioner
Namnge variabler och funktioner på ett sådant sätt att namnet förklarar syftet med variablen eller funktionen. Om du behöver lägga en kommentar för att förklara behöver namnet förtydligas.
Exempel
let pageNode;
let pageName = getPageNodeAsStringOrfalse(pageNode);
Hantering av CSS i Sitevision
Försök minimera antal CSS-klasser som skapas i Sitevision. Använd om möjligt en omslutande class och manipulera övriga CSS-komponenter i förhållande till den.
Exempel
.vrd-news-list-on-startpage-top li
.vrd-news-list-on-startpage-top liExterna ramverk
Inga externa ramverk får laddas från andra servrar. Om det inte efterfrågas av beställaren. Om extern kod ska användas ska den i första hand laddas från webbsidan.
Dokumentation
Vi jobbar alltid med dokumentationen i samband med utvecklingen. Ta för vana att skapa en enkel beskrivning av funktonen innan du börjar utveckla. På så sätt få du en övergripande dokumentationen. Det kan också hjälpa till att identifiera problem eller behov av förändringar i koden på ett tidigt stadium, vilket kan spara tid och resurser i längden.
Metadata
När du planerar och skapar metadata är det viktigt att tänka på att det ska vara användarvänligt och lätt att förstå för redaktörerna som arbetar med innehållet. Det är också viktigt att metadata-namnen är logiska och konsekventa för att undvika förvirring och felaktig hantering av innehållsobjekt.
Dokumentera alltid din metadata så att det finns en översikt över de olika metadata-fälten och deras syfte och användning. Detta kommer att hjälpa både redaktörer och utvecklare att förstå och använda metadata på ett korrekt och effektivt sätt.