Hur kommenterar man på bästa sätt?

Det behövs inga manualer till t.ex. bilar heller då? Varför beskriva för någon hur vindrutetorkarna opereras, när han/hon kan plocka isär hela bilen och kartlägga kretskorten och sladdarna?

Nä, lägg ner det där. En klass/funktion/metod har uppgiften att utföra något åt andra programmerare utan att de ska behöva veta hur den är implementerad.

Om du har problem med att förklara med ord vad koden gör, börja döp dina variabler till a, b, c osv.


Ska jag döpa min förbättrade implementation av fgetc() till readTheNextCharacterFromStreamAndReturnItAsAnUnsig nedCharCastToAnIntOrEOFOnEndOfFileOrError()?

Jämförelsen haltar. En vindrutetorkaren startas genom att man använder reglaget med rätt symbol. Bilförare känner till den symbolen och behöver inte läsa manualen. Om man behöver läsa manualen så har man som designer av kontrollerna i bilen gjort ett dåligt jobb. Alla kontrollera ska vara intuitiva och man ska inte behöva läsa en manual för att hantera bilen.
En programmerare läser metodnamnet och förstår utifrån den vad koden gör. Om man behöver läsa kommentarer så har den som skrivit metoden gjort ett dåligt jobb.

Det är få som säger att man inte behöver kommentarer alls. Ibland tvingas man göra lösningar som är väldigt komplexa och som vanliga programmerare inte kan förväntas förstå eller så har man tagit en genväg och då SKA man kommentera det så att det hacket rättas till när mer tid eller kunskap finns.

Man får hitta en medelväg. I Java så beskriver metodsignaturen mer än i C så bara där får man hjälp vad som händer.

Vad gör din förbättrade fgetc()? Jag tycker den beskriver just vad fgetc() gör.

Tycker att du kan halta. Alla programmerare är inte bilförare. Du kan behöva förklara att när metoden switchGear(int gear) anropas, måste clutchDown() ha anropats innan, hastigheten på bilen ska vara högst 50% lägre eller högre än rekommenderad fart för växeln, och kanske t.o.m. hur många växlar det finns.


Det gäller kanske för användare, till en viss gräns, men från programmerare ska man väl kunna kräva mer? Annars kommer det inte gå att optimera någonting.


Japp, det är bara implementationen som är förbättrad

Help.

Någon som vet hur man kan börja komma igång med att strukturera?

Vad menar du egentligen med att strukturera?

Det är bara att börja. De flesta IDE:er har bra refactoringverktyg som gör det lätt att flytta omkring kod utan att förstöra det som fungerar.

Först behöver du hitta något som inte är bra. Vad är det som är dåligt? På vilket sätt går det att göra bättre? Är det värt ändringen? Om ja, så gör det.

Använd ett versionshanteringssystem. Då kan man ge sig på stora ändringar utan att behöva fundera så mycket på om man verkligen kommer att lyckas. Fungerar inte ändringarna så är det bara att göra revert. Ändringar som tar lång tid att genomföra gör du lämpligtvis i en egen branch för att inte störa produktionskoden.

Vi kör SonarQube/Sonar för statisk kodanalys. Till Eclipse finns pluginen SonarLint som gör samma sak utan att ha SonarQube körande. Sonar hittar många problem med koden och ger hjälp till hur man ska lösa dem.