Skrivet av Ernesto:
Jag tycker att det är viktigt att skilja på kommentarer och dokumentation - De är nämligen inte samma sak, även om man kanske kan klassa dokumentation man skriver till en function som en kommentar, så är ju syftet något helt annat.
Lite obehagligt att det skulle dröja till inlägg 164 i tråden innan detta togs upp (med brasklapp för att jag missat något).
Jag är en kommentarslaktare av rang när det gäller kommentarer som lagts till inuti metoder och funktioner, just av övertygelsen att dessa kommentarer allt som oftast bara är ett tecken på att funktionen är för stor och borde brytas upp i fler mindre och väldefinierade funktioner. Detta ger en stor boost i testbarhet, och om man har som ryggmärgsreflex att skriva tester under utveckling så borde det snabbt bli lika reflexmässigt att eftersträva små isolerade enheter att testa.
Samtidigt förespråkar jag att dessa isolerade enheter ska vara dokumenterade för att förtydliga intentionen. Bra namngivning av olika entiteter (moduler, klasser, funktioner, variabler, …) räcker långt, men dokumentation är i mina ögon ett nödvändigt komplement. För en insatt programmerare är koden i sig typiskt tillräckligt självförklarande för att förklara hur den fungerar (så länge den följer vanliga språkidiom, designmönster, etc.), men att svara på varför den existerar kan ofta vara en annan sak, och går generellt inte att koda ner i funktionsnamn om man inte går till absurditeter i namngivning.
En annan användbar aspekt på att "behöva" skriva dokumentation är att det ofta kan bli väldigt tydligt ifall designen börjar då söderut. Spindelsinnet börjar pirra när man märker att dokumentationen börjar kännas komplex. Kan man inte någorlunda enkelt förklara vad en funktion gör så finns det stor risk för att designen är dålig, eller i andra ord:
Skrivet av Tim Peters:
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
En tumregel är att om en kortfattad sammanfattning av vad en funktion gör behöver innehålla "and" eller invecklade bisatser så kanske den borde brytas upp än mer. En kusinregel är att om man trots ansträngning inte lyckas hålla sig till 50/72-regeln för commitmeddelanden i Git så kan det vara ett tecken på att ens commit borde varit flera.
En annan metod för att argumentera mot kommentarer är att det som är skrivet som en kommentar ofta skulle kunna passa som ett loggmeddelande på någon passande nivå (eller i andra ord: en kommentar som skulle kunna passa som ett loggmeddelande är sannolikt en "dålig kommentar" som borde varit ett loggmeddelande, eller tagits bort). Ett trolleritrick jag tycker mig ha hittat är att så fort en sådan text blir "exekverbar" och får en reell sidoeffekt så minskar risken dramatiskt för att den ska bli utdaterad.
Även om det är loggning på en nivå som typiskt inte dyker upp vid vanlig användning så är det som om ett loggningsanrop medför större respekt än kommentarer, och den sekund då det är nödvändigt med debuggning så får man direkt återbäring på dessa meddelanden. Det finns rätt få/inga tillfällen då jag har önskat färre loggmeddelanden när en användare har upplevt något oväntat beteende.
Skrivet av Ernesto:
Han hade kunnat klargöra sin kod antingen med kommentarer, eller variabler/metoder - Ibland måste man ha en kommentar varför en sak är som den är, men metoden, eller variablen som sådan, bör vara namngiven på ett sånt sätt att man egentligen aldrig behöver fråga sig varför - Jag ser ju i koden att han skapar en rekyl på vapnet, mer än så behöver man ju nästan aldrig
Det finns ett "varför" till som jag inte har sett nämnas så mycket i tråden: när man medvetet behöver skriva kod som kan se oväntad ut i en viss kontext, men av en god anledning: där ser jag nyttan av kommentarer. Det kan vara workarounds för buggar i externa bibliotek/OS, det kan vara platser där man fått lämna vanliga idiom av speciella prestandaanledningar, märkliga infrastruktursavvägningar eller nödvändig kompatibilitet med något externt otrevligt beroende.
Jag gillar inte att bli överraskad när jag läser kod. Jag vill inte se "kluriga" lösningar på problem som har välkända lösningar. Blir jag överraskad så ska det vara av en anledning, och då får personen gärna ha motiverat denna anledning. Det är möjligt att ett commitmeddelande kan räcka om man nu skulle vara patologiskt allergisk mot kodkommentarer, men det kan också leda till en häxjakt efter att modulen kanske har flyttats runt eller liknande så att man får jaga bakåt i revisionerna.
Jag vet tillfällen i närtid då jag jagat kod bakåt över mer än 20 revisioner för just det blocket, inklusive flera refaktoreringar och ett par filflyttar bara för att försöka få en ledtråd till varför en viss icke-idiomatisk lösning valts. Hade det funnits en kommentar i koden så hade den sannolikt överlevt denna resa och kunnat spara tid.
Skrivet av Ernesto:
Sen efter 10 år börjar man förstå hur otroligt jävla urusel man är och att man skriver riktigt jävla dålig kod, otroligt ovärdig, borde bli kycklingfarmare. Då är man på god väg att börja bli riktigt värdefull.
Just 10 år är en tidsram jag själv, på tal om tumregler, tycker har en speciell innebörd. Då är det ej heller bara 10 år av samma "slöprogrammerande", utan med varierande utmaningar (högt och lågt, praktiskt och teoretiskt) och en aktiv inställning att lära sig nya saker.
Typiskt verkar det vara där någonstans stenhårt kategoriska åsikter börjar mjukas upp, och ödmjukheten inför sin egen okunskap har passerat sitt minimum och åter börjar svinga uppåt ("kycklingfarmareffekten"). Då menar jag inte nödvändigen 10 år av universitetsstudier eller arbete, utan 10 år av att ha levt med programmeringen i sin närhet, låtit tankesätt sjunka in, ha sett många aspekter och åtminstone några trender komma och gå.
Man är inte ensam: Teach yourself programming in ten years [Peter Norvig] ("Director of research at Google", ifall man lägger värdering i vem som säger saker utöver budskapet i sig).
Som vissa i tråden också argumenterar för så är det sällan svart eller vitt. Inte minst de tumregler som jag nämnde ovan är just tumregler snarare än absoluta sanningar.
Skrivet av Ernesto:
Man läser ju otroligt mycker mer kod än man skriver, det är absolut vitalt att koden man läser är lättläst - Ju mer likt naturligt språk, ju fortare kan man läsa den.
"Readability counts", för att återigen tillkalla Tim Peters .
