Clean Code
Kommentek helyes használata
Mikor felesleges, mikor hasznos a komment, és miértet érdemes dokumentálni.
Kommentek helyes használata
A kommentekről sokan azt gondolják, hogy több komment = jobb kód. Ez téves. A komment a kód kommunikációs kudarcának jele, ha arra használjuk, hogy elmagyarázzuk, mit csinál a kód.
Mikor NE használj kommentet?
Ha a kód magától értetődő, a komment redundáns és zavart kelthet.
// ❌ Rossz – a komment csak ismétli a kódot
// Növeli az i értékét egyel
i++;
// Visszaadja a felhasználó korát
function getUserAge(user) {
return user.age;
}// ✅ Javított – komment nélkül is érthető
i++;
function getUserAge(user) {
return user.age;
}Mikor szükséges a komment?
A komment akkor értékes, ha kontextust ad, amelyet a kód önmagában nem tud átadni.
// ✅ Jó komment – magyarázza a "miértet"
// A Blowfish algoritmus szándékosan lassú, hogy megnehezítse a brute-force támadásokat.
const hashedPassword = bcrypt.hashSync(password, 12);
// A böngészők közötti kompatibilitás miatt setTimeout(0) szükséges itt,
// hogy a DOM frissítés megelőzze az eseménykezelőt.
setTimeout(() => updateUI(), 0);// ✅ Jó komment – TODO, amelyet nyomon követünk
// TODO: Cseréld le REST API hívásra, amikor a v2-es endpoint elérhetővé válik (#TICKET-1234)
const userData = mockUserData;Kikommentezett kód – töröld el
Az elavult, kikommentezett kód szemét, nem dokumentáció. A verziókezelő (git) megőrzi a történelmet.
// ❌ Rossz – zavart és bizonytalanságot kelt
// function oldCalculation(x) {
// return x * 1.8 + 32;
// }
function celsiusToFahrenheit(celsius) {
return celsius * 1.8 + 32;
}// ✅ Javított – csak a jelenlegi megvalósítás marad
function celsiusToFahrenheit(celsius) {
return celsius * 1.8 + 32;
}Rövid összefoglaló
- A komment a kódírás sikertelensége, ha magyarázni kell, mit csinál a kód – inkább javítsd a kódot.
- Kommentáld a miértet, ne a mitélt.
- Kikommentezett kódot töröld el – erre való a git.