-
Notifications
You must be signed in to change notification settings - Fork 23
Konvensjoner og workflow i OW4
Kode som skrives til ow4 skal støtte IE9 eller høyere, samt versjoner av andre nettlesere med tilsvarende støtte.
Vi ønsker å ha en ren kodebase som skal være mest mulig lik over hele fjøla. Derfor er det viktig at alle følger de samme konvensjonene når vi skriver kode.
JavaScript-koden i ow4 skal kjøres i strict mode, og skrives med tilstrekkelig bruk av JSLint/JSHint. Dette vil dog forhindre bruk av nyere syntaks, men vil bevare en definert struktur gjennom alle JavaScript-filene våre. Dette gjøres ved å definere 'use strict'; i toppen av alle JavaScript-filer.
- semikonol skal forekomme etter alle statements
- et innrykk skal bestå av 4 mellomrom
Alle funksjoner skal være deklarert før de benyttes. Det skal alltid være et mellomrom mellom nøkkelordet function parentesen:
function () { ... }I navngitte funksjoner skal parentesene følge etter funksjonsnavnet, uten mellomrom:
function MinFunksjon() { ... }Alle funksjoner skal defineres som et uttrykk:
var funksjonsnavn = function () {
// ...
};Ikke denne måten
function funksjonsnavn() {
// ...
}Alle variabler skal starte med liten forbokstav. Vi benytter oss av camelCase i variabelnavn. Alle variabler skal defineres med nøkkelordet var for å unngå at alt går ut på global scope:
var minVariabel = '...';Klassenavn skal alltid starte med stor forbokstav. Vi benytter oss av CamelCase i klassenavn når vi skal sette sammen flere ord. Klassefunksjonen skal også være definert med navn:
var MinKlasse = function MinKlasse() {
// ...
};Funksjonsnavn skal alltid starte med liten forbokstav. Vi benytter oss av camelCase i funksjonsnavn når vi skal sette sammen flere ord.
Konstruktøren skal se slik ut
var MinKlasse = function MinKlasse() {
// ...
};Objektmetoder defineres på funksjonens prototype:
MinKlasse.prototype.minFunksjon = function () {
// ...
};Statiske metoder defineres direkte på klassen:
MinKlasse.minStatiskeFunksjon = function () {
// ...
};var Utils = function Utils() {
// Alltid ha med definisjonen selv om den er tom
}
Utils.makeApiRequest = function (request) {
$.ajax({
url: request.url,
error: function (error) {
request.callback(error);
},
success: function (data) {
request.callback(null, data);
}
});
};Benyttes på denne måten:
Utils.makeApiRequest({ ... });var ArticleWidget = function ArticleWidget() {
var self = this;
Utils.makeApiRequest({
url: '',
callback: function (err, data) {
self.render(err, data);
}
});
};
ArticleWidget.prototype.render = function (err, data) {
if (err) {
// håndter feil
return;
}
// behandle data
}Benyttes på denne måten:
new ArticleWidget();Hold JavaScript-filene rene. Unngå å benytte unødvendig mange closures. Slik koden er strukturert per i dag er det best at hver klasse blir eksponert per klasse. Lokale funksjoner vil uansett være lokale til disse klassene.
Alle JavaScript-filer skal inkluderes i bunn av HTML-dokumentene (med mindre annen funksjonalitet er tiltenkt). Derfor trenger vi heller ikke benytte oss av jQuerys ready-funksjon.
OW4 benytter seg av LESS for å gjøre stilskrivingen mer oversiktlig for utvikleren. LESS introdueserer mange nyttige måter for å strukturere koden på, men da også en del fallgruver.
Vi ønsker å unngå så mye nøsting som mulig. La nøstingen være et minimum. Vi vil ikke overdrive klassebruk, men ei ønsker vi å overdrive nøsting.
- la 3 nivåer være en pekepin for maksimum antall nøstede regler
- bruk beskrivende klasser fremfor nøsting
- prefix klasser med kontekst for å unngå kræsj
Vi vil derfor ikke skrive noe slikt:
#article {
header {
.author {
.name { ... }
.mail { ... }
.img {
.description { ... }
}
}
}
}Dette er oversiktlig for deg som skriver kode, men vil være døden for større nettsider (da med høy trafikk og mye krevende innhold). Legg her merke til at nivå 5 vil tolkes i CSS-koden som:
#article header .author .img .description {
...
}Som da vil si at den prosesseres 5 ganger før de tiltenkte elementene er valgt. Nå vil ikke ow4 generere særlig mye trafikk, og innholdet vil ikke være krevende for en nettleser. Men good practice er alltid en fin ting.
Skriv heller:
.author-img-description {
...
}ev. prefix den med:
.article-author-img-description {
}En annen ting ved dette er at det vil være mer forståelig for en bruker å se hva et element skal være når den inspiseres i nettleseren. Si du har et blått felt i transaksjonen din i nettbanken. Du ønsker å se hva den gjør. Utvikleren har skrevet koden slik:
ul#transactions {
li {
&.blue {
color: blue;
}
}
}Når elementet inspiseres vil du få opp
li.blue { color: blue; }og du må gå bakover i treet for å finne ut at det er:
ul#transactions li.blue { color: blue; }Men du blir egentlig ikke noe klokere. Hva om den ble skrevet som dette:
.not-paid {
color: blue;
}Når den inspiseres så ser du med en gang hva den fargen gjør. Selv om en bruker aldri skal komme dit at han/hun må inspisere kode for å finne ut hva nettsiden prøver å si, så vil du som utvikler havne i samme knipe når du senere blar opp koden og lurer på "hva søren var det den fargen skulle indikere?".
Samtidig. Aldri benytt tomme nøster (her er #gruppe helt tom):
#gruppe {
.regel {
font-size: 12px;
}
}.lag-da-heller-en-beskrivende-klasse {...}
Samt, ID-er trengs ALDRI å nøstes:
.klasse1 {
#id1 {
font-size: 14px;
}
}Vi skal slutte med å merge kode inn i onlinewebben selv. Målet er å bruke pull requests på Github til å gjøre dette.
Pull requests fungerer slik at andre i dotkom kan se gjennom koden du har skrevet før den havner i repoet med alt annet arbeid vi gjør. Dette lar oss fået bedre overblikk over hva slags kode som flyter gjennom git, og eventuelt rette opp f.eks. feil eller mangler i dokumentasjon før endringene merges.
Mer info om pull requests kan finnes på github sine hjelpesider for collaboration: https://help.github.com/categories/63/articles
Vi koder for et stort sett norskt publikum, derfor gir det mest mening at vi holder verbositeten til norsk.
Eksempel:
location = models.CharField("beliggenhet", ... )
I tillegg ønsker vi å tilby oversettelse av alt vi uttrykker på norsk gjennom kode i webben. Dette gjøres med en translate funksjon som fins i django.
Vi bruker ugettext for dette:
from django.utils.translation import ugettext_lazy as _
Det blir dermed seende slik ut:
location = models.CharField(_("beliggenhet"), ... )
Mer om translation i django kan man finne i dokumentasjonen. En link om lazy: https://docs.djangoproject.com/en/dev/topics/i18n/translation/#lazy-translations
Forsidden er bygget opp av flere forskjellige seksjoner. Disse seksjonene inneholder deretter underseksjoner. En enkel måte for å skulle mellom seksjonene, og innholdet,samt permlinke til spesifikt innhold bygger vi opp lenkene innad i forsiden slik:
/#seksjon/subseksjon
Eks. lenke til dotKom under about/om Online: /#about/dotkom
på denne måten kan vi enkelt hente seksjon, og underseksjon, samt lenke direkte til innholdet.
Når vi skal hente url til en modell, så skal vi ikke bruke {% url name_of_view kwargs %}, men <a href="{{ object.get_absolute_url }}"></a>
Basically involverer dette at modellene selv vet hvordan de skal lenkes til, og reversing av url forgår i modellen.
Dette er mer utfyllende forklart her; https://docs.djangoproject.com/en/dev/ref/models/instances/?from=olddocs#the-permalink-decorator