JavaScript & Agila, 40 + 10 YHP

Mörkt tema

Kommentarer och dokumentation ​

⏰ Tidsåtgång: c.a. 10 min

💡 Introduktion till ämnet (flipped classroom) ​

Kommentarer ​

💬 Transkription

Kommentarer är ett ovärderligt verktyg när man precis lär sig någonting. Kommentera ofta, tills du förstår.

I CSS skrev vi kommentarer genom att skriva /* och avsluta med */. På samma sätt gör vi i JavaScript.

Men vi kan även skriva enradskommentarer genom att skriva //.

js
// Denna kommentar är på en rad, det går inte att göra radbrytningar.

/* Detta är en så kallad blockkommentar.
  Den kan gå över flera rader.
 */

/**
 * Det är vanligt att formatera sina kommentarer såhär.
 * Dvs. två stjärnor i början, och sedan en per rad,
 * när man skriver blockkommentarer.
 */

Hur du kommenterar nu i början är upp till dig. Jag rekommenderar varmt att skriva kommentarer där det behövs.

Men en grundregel som programmerare är att kod ska vara självdokumenterande. Med det menas att du ska namnge saker och ting på ett sådant sätt, att kommentarer i viss mån är överflödiga. Det kommer inte att gå i början när allt är nytt, men successivt är detta någonting som du ska eftersträva.

Ponera att du har en webbplats med en "Om oss"-sida. Din uppgift är att byta font-storleken på rubriken på den sidan.

Om du jämför selektornernas namngivning i CSS-koden nedan, så kan du med stor sannolikhet snabbare avgöra vilken av dessa selektorer som är den du ska ändra i, utan att behöva titta i HTML-koden.

css
.brown {
  font-size: 24pt;
  text-align: center;
  text-decoration: underline;
  color: brown;
}

.about-page h2.main-heading {
  font-size: 24pt;
  text-align: center;
  text-decoration: underline;
  color: brown;
}

På samma sätt bör vi skriva får JavaScript-kod (och all annan kod). Oroa dig inte för vad syntaxen betyder ännu, men bara genom att läsa koden så kan du förmodligen avgöra, vilken sorts program den tillhör:

js
const dealtCards = ['Ace of Spades'];
const points = 20;

function shuffleCards() {
  cardsLeft.shuffle();
}

function drawOneCard() {
  cardsLeft.draw();
}

Jämför nedan kod, som teoretiskt gör exakt samma sak:

js
const a = ['Ace of Spades'];
const b = 20;

function sh() {
  cl.shuffle();
}

function draw() {
  cl.draw();
}

Helt obegripligt ☝️.

📖 Läsanvisningar ​

🏋️ Övningsuppgifter ​

Grund ​

Dokumentera följande kod
html
<script>
  function drawCard() {
    cardsLeftInStack.draw();
  }
</script>

Next level ​

JSDoc

När man börjar närma sig en senior utvecklarroll förväntas det att man också dokumenterar sin kod. Man försöker följa koddokumentationsstandarder och det kan vara värt att bekanta sig med JSDoc för att se hur det är brukligt att skriva kommentarer i sin kod.

✅ Avstämning ​

Använd denna lista för att "checka av" att du förstår modulens koncept.

Terminologi
  • Kommentarer
  • Enradskommentar
  • Blockkommentar
  • Självdokumenterande kod
Du är klar när…
  • Du vet hur och när du skriver kommentarer
  • Du vet vilka olika typer av kommentarer det finns
  • Du har bestämt dig för att eftersträva att skriva självdokumenterande kod

❓ Våga Fråga ​

Resurser ​

Happy coding!