Skrivet av WebbkodsFrilansaren:
[li]En rolig kontrast mellan ditt PHP-projekt och mitt JS-projekt är att du har inga kommentarer och det som slog mig då var hur klurigt det kan vara att få ett grepp om varför diverse kod ligger i de filer de ligger i, i vilken ordning, och så vidare. Eller så är jag bara "korkad"! Jag tänker att korta vägledande kommentarer kan ge mentalt stöd som snabbt förklarar kontexten för diverse "kodparagrafer" än att ytterligare mentala resurser ska läggas på att både läsa koden och lista ut varför den ligger där den ligger (varför var någonstans i filen och varför i just den filen, och så vidare). Vid "deployment" så kan man väl ändå ta bort kommentarerna? Vissa företag verkar dock ha policy att "förbjuda kommentarer" vilket jag tycker är konstigt: varför göra det mentalt mer ansträngande att läsa kod om man kan göra det enklare? [/li]
Kan inflika på den här kommentaren, nu när jag har några års erfarenhet av professionell utveckling. Kommentarer är bra och viktigt för nya utvecklare mer än det är för mer seniora, av olika skäl.
Många nybörjare får lära sig att man ska kommentera sin kod och får exempel som detta:
// Set active flag to "false" in each element in Results
for (const element of Results) {
element.Active = "false";
}
Denna sorts kommentarer omformulerar egentligen bara vad exakt det koden redan säger, fast på läsbar engelska. För en nybörjare kan det kanske vara behjälpligt, men efter man har kodat ett tag så kan man se på själva koden exakt vad den gör utan att behöva läsa en sammanfattande beskrivning, dvs så är kommentaren helt redundant.
Sen brukar oftast sådana kommentarer som ovan också snabbt bli utdaterade och kanske tillomed ljuga om vad som händer. Skulle man exempelvis lägga till att den också ändrar "lockedDate" fältet på elementet så kan det se ut såhär:
// Set active flag to "false" in each element in Results
for (const element of Results) {
element.Active = "false";
element.LockedDate = Date.now();
}
Om jag nu inte kommer ihåg att ändra kommentaren och lägga till att den också sätter LockedDate så kommer ju kommentaren vara fel. Du kan också själv ha missförstått vad en viss funktion eller bibliotek gör, så beskriver du den med egna ord på ett sätt som är felaktigt, så kanske nästa programmerare litar på dig och då introducerar en bugg när den använder sig av din kod. Den enda säkra sanningen om vad som faktiskt kommer hända när man koden är vad koden själv säger, inte en ev. kommentar.
Även kommentarer som beskriver en viss längre funktion kan vara lite redundant. Ta följande exempel:
// Gets the user info given an user id and all their permissions and access in the given group. Also logs this access to the db.
function getInfo(id, group) {
...
}
Här kanske en kommentar verkar vettig? Det kanske är 100 rader kod som gör saker och det är inte helt tydligt vad "getInfo" gör bara genom att läsa namnet. Och vad är id och group egentligen om man inte läser kommentaren? Här är lösningen inte heller nödvändigtvis att man lägger på en kommentar i många fall, utan snarare att man behöver vara tydlig med vad funktionen egentligen gör i redan i funktionsnamnet. Kanske behöver man dela upp funktionen i mindre funktioner för att få en bättre förståelse och översikt om vad som händer? Lösningen hade kanske därför varit något i stil med:
function getUserInfoAndGroupPermissions(userId, groupId) {
const userInfo = getUserInfo(userId);
const groupInfo = getUserPermissionInGroup(userId, groupId);
logAccess(userId, groupId);
return { userInfo, groupInfo };
}
Genom att köra på det andra sättet så får man dessutom mer hjälp av ens editor med vad som förväntas skickas in som parametrar när man skrivit klart funktionsnamnet. Sen går det ju förstås att göra det extra tydligt vad den gör med kommentarer också, iaf om man skriver ett bibliotek som andra kan tänkas använda som inte är införstådda i din kod. Men då behöver man oftast bara skriva kommentarer för de funktioner som exponeras för användarna, inte nödvändigtvis de som bara används internt av biblioteket.
När man ska använda
De tillfällen kommentarer kan vara riktigt bra dock är att beskriva VARFÖR man gjort på ett visst sätt, snarare än vad koden gör. Exempel skulle kunna vara:
....
const user = getUser(userId);
// If user has many ongoing orders, we need to block them by adding them to CreditGroup: F0001 which corresponds to "blocked" in SAP
if (user.pendingOrders > 10) {
user.metatag["CreditGroup"] = "F0001"
}
...
Här är det tydligt att man inte fattat vad F0001 betyder eller varför man gör som man gör utan en kommentar. När behovet av att öka antalet ordrar ändras, så behöver kommentaren inte uppdateras. Och skulle man inte behöva denna block längre så tar man bara bort kommentaren samtidigt som koden.
Sammanfattning
Det är nödvändigtvis inte dåligt med kommentarer, men ju mer erfaren du är och ju större och snabbt förändrande projekt du jobbar i så är många av dem redundanta och skapar mest trubbel när behoven ändras. Kommentarer som förklarar vad koden gör bör undvikas, men kommentarer som förklarar varför koden gör något kan vara mycket nyttigt.
