Retningslinjer for kodekvalitet

For at koden vi lager skal ha tilstrekkelig kvalitet er det et par ting vi må passe på. I beskrivelsen som følger vil det oppklares om hvilke konvensjoner som forventes.

---

Forsikring av kodekvalitet

For å forsikre en tilstrekkelig kodekvalitet tar prosjektet i bruk ESLint som en del av workflowen i Github Actions. Dessuten er det forventet at alle bruker et kodeformatteringsverktøy som Prettier, slik at alle filer er ryddige og lesbare.

Navngiving av brancher

En branch skal navngis på en måte som forklarer dens hensikt på en klar og tydelig måte. Navnet skal være formattert slik:

[feat/ref/chore]/<hva som er nytt>

Et fornuftig navn kan for eksempel være

feat/implemented-calendar

eller

ref/calendar-select-bug

Det siste eksempelet omhandler altså en refaktorering som fikser en bug i kalenderkomponenten.

Praksis for god kvalitet av komponenter i React

Det er mange forskjellige måter å implementere en komponent i React. I dette prosjektet ønsker vi å følge de nyeste når det kommer til å lage gode og fleksible komponenter.

En veldig bra videoressurs som jeg sterkt anbefaler er denne - https://www.youtube.com/watch?v=MSq_DCRxOxw&ab_channel=CoderOne

TLDR;-en på videoen er som følger:

• Programmer alltid med SOLID-prinsippene
  • S - Single responsibility principle: Ikke la en komponent gjøre alt. Del den opp i mindre biter, som til slutt bygger opp det endelige resultatet som du er ute etter. Eksempel: Ikke la headeren både hente inn data fra backend, og vise den. All nettverkslogikken bør flyttes ut av komponenten slik at den blir så enkel som mulig.
  • O - Open-Closed principle: Open for extension, closed for modification. Dersom en type utvides til å støtte flere valg bør koden kunne legge til rette for dette uten at man må legge til mer logikk i komponenten.
  • L - Liskov Substitution: (Denne er veldig viktig) Dersom man lager en komponent som bruker en komponent fra et annet sted som har veldig mange ulike props, er det i noen tilfeller veldig gunstig å gjøre disse tilgjengelige for den koden som bruker komponenten du har laget. Eksempel: Du har laget en komponent som heter Button. Den bruker det innebygde HTML <button>-elementet, og denne har mange ulike props (eksempelvis onClick, onMouseOver etc.). I dette tilfellet er det gunstig å gjøre disse props-ene tilgjengelig gjennom propsene til Button-komponenten din. Se videoen for hvordan man gjør dette.
  • I - Interface Segregation: Ikke gjør en komponent avhengig av typer som inneholder mye mer enn det den selv trenger. Se videoen for mer utfyllende eksempel.
  • D - Dependency Inversion: Gjør komponenten så generell som overhodet mulig. Den skal kunne fungere i en hvilken som helst kontekst. Se videoen for mer utfyllende eksempel.

Navngiving av komponenter

Ettersom at dette prosjektet bruker shadcn, som allerede har sin egen (og litt sære) navngivingskonvensjon, velger vi å følge denne. Hvis det er noe tvil, skal filnavnene være slik: data-table.tsx (Kebab case) mens selve funksjonsnavnene inne i filen skal være i Pascal case (DataTable)

Statiske ressurser

Som nevnt i vercel sin dokumentasjon, skal statiske ressurser slik som bilder og lydfiler lagres i /public, og ikke i /src-mappa. Dette er for å optimalisere ytelsen av nettsida ettersom at /public er en statisk mappe.

Se denne lenka for mer informasjon: https://nextjs.org/docs/pages/building-your-application/optimizing/static-assets

Dokumentasjon av koden

Vi ønsker at denne kodebasen skal være så enkel å vedlikeholde som overhodet mulig. Som noen kanskje har lagt merke til, så kan dette være en utfordring i Kvark.

Dersom det kan være uklart hva hensikten til en komponent er, er det veldig ønskelig at man dokumenterer dens hensikt ved hjelp av JSDoc. Det trenger ikke å være noe veldig avansert! Her er et eksempel:

Dersom komponenten kun skal brukes én gang, og den er veldig liten er ikke dette nødvendig. Men hvis du befinner deg i denne situasjonen - kanskje du bør vurdere om du egentlig trenger å gjøre det om til en egen komponent?

...Og sist men ikke minst!

Der er bare å si ifra hvis noe virker helt tullete, eller om det er noe tvil om hvordan en ting skal gjøres. Vi skal jobbe sammen om å lage et bra produkt, og da er det viktig med innspill!