Kommentarer är av ondo

Haha ja det där är ju missbruk av kommentarer. Men har inte det mer att göra med okunskapen att skriva kod snarare än kommentarer?

Till exempel så finns det ju någon oskriven regel(?) som säger att alla namn på bool/boolean (eller logiska typer med 1/0 eller true/false utfall) bör börja på ett verb. På engelskan blir det is och has/have. Så man får då funktioner och variabler som heter: isUser(), isLocked, hasTickrate, o.s.v.

Så likt ditt exempel så får man:

// Check if server is running and has a tick rate. <= Brutalt onödig kommentar
if(isRunning == true && hasTickrate == true)
{
    code...
}

eller...

// Check if server is running and has a tick rate. <= OK kommentar, men dålig kod
if(system == true && tick == true)
{
    code...
}

I det fallet så tror jag det har mer med att man inte är så haj på att skriva lättläst kod, snarare än att man gillar att skriva kommentarer. Då försöker man täppa till den biten som är svårläst kod med kommentarer, och till slut är halva filen fylld med kommentarer. Eller så är man själv osäker och försöker förtydliga koden för sig själv. Det är vad jag tror men kan ha fel

Jag har aldrig varit med om en IDE som klarar hantera en extern doc-fil lika sömlöst som när dokumentationen ligger direkt i koden, men det kanske finns. I vilket fall som helst så är det mycket lättare att ha dokumentationen direkt i koden för saker som code-reviews och att spåra när ändringar gjordes tycker jag.

Om man sitter i ett språk där det finns built-in support för det du gjorde, eller om man har möjlighet att dra in libs som gör det, så är absolut din kod ett bättre alternativ för just det här exemplet. Dock har man inte alltid möjlighet till det och då är det bättre att lägga en kommentar än att inte ha något alls. Att lagra 1000*60*60 i en extra konstant som heter tex. 1_HOUR låter som en väldigt ful lösning tycker jag jämnfört med att bara lägga en kommentar.

Om man bortser från IDE-integration så ser jag inte riktigt hur din lösning skilljer sig eller skulle vara bättre än en kommentar. Vad jag kan se uppfyller den exakt samma funktion men är bara mindre lätt-läslig eftersom den innehåller kod-syntax. Men det är kanske så man gör för att IDE's i det språket ska highlight'a den som Obsolete åt en och då är det ju att föredra för att få proper integration med IDE'n. I Java's fall så gör ju en kommentar det.

Om vi ändå diskuterar best-practice när det kommer till kodning: Att skriva bra commit-kommentarer är mycket viktigt. Nu kanske detta print-screenet bara är på ett flum-projekt, och du redan vet om detta, men en commit-kommentar ska beskriva tydligt vad man gjort och varför man gjorde det. Anledning för detta är för att då kan man enkelt se varför koden på en rad ser ut som den gör, och då kan man ofta slippa många onödiga kommentarer. Ett rätt dåligt exempel (för detta är bara ett hobby-projekt jag sitter själv på så jag skriver inga super commit-kommentarer) men:
https://i.imgur.com/zw9Z8dP.png
Här finns tack vare en decent commit-kommentar en tydlig förklaring till varför koden på rad 52-60 ser ut som den gör. Hade commit-kommentaren bara varit "Fixed X" så finns det stor risk att någon i framtiden kanske skulle få för sig att ändra detta och då få problem på massor av ställen i koden och åter-introducera buggar. Om det nu är så att man ska ändra koden här ändå så kan man tack vare commit-kommentaren göra det på ett säkert sätt, för man vet vilka problem som tidigare funnits här och kan på så vis undvika att återskapa dom. Säger commit-kommentaren bara "Fixed X" så finns det risk att man un-fixar det såvida kod-ändringen för den kommentaren inte är självklar.

Efter att ha suttit flera gånger och debuggat komplicerad kod efter något problem som uppstått när en semaphore eller något har plockats bort av en commit med en kommentar som säger "Fixed X" så är dåliga commit-kommentarer det första jag underkänner en commit på review för.

Första raden i commiten ska vara en kort och koncis text ja. Men man kan ha flera rader som då ofta göms när man listar flera commits, men visas när man tittar just en commit. I scenarion som jag visade ovan hade det sugit röv om varje commit bara länkade till ett issue nummer istället för att ha en tydlig beskrivning, det hade tagit 10 gånger så lång tid att reda ut. Men självklart ska också en commit-kommentar länka till issue nummer om det finns ett sådant för den, men inte istället för att ha en bra beskrivning.

Kul discussion!

Alltid roligt att man så snabbt kan sortera vilka som läst Robert Martin och vilka som inte har det.

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.

Att dokumentera och beskriva ett API och liknande är ju otroligt viktigt för att underlätta integration för tredjepart, men det är ju en försvinnande liten del av koden som är en yta utåt, den mesta koden ligger ju mest troligtvis i domänen (koden som är specifik för din produkt). Eventuellt API är ju mest troligt bara en yttre som skickar vidare anrop mot andra servicar eller liknande.

Jag skriver enbart kommentarer när jag designar en metod eller ett test - Jag radar upp vad metoden eller klassen ska göra, sen börjar jag implementera - Oftast rakt upp och ner i en jätteklass eller jättemetod, varje funtion under varje rad kommentar.

Sen tar jag oftast all kod mellan två kommentarer, och bryter ut den. Metodernas namn ersätter kommentaren. Ungefär så här:

public class UserService
{
	public User GetUser(Guid userId)
	{
		// validate access
		// Get user from repository
		// Get user data from data service
		// Get user salary data
		// Transform user
		// Log that user has been fetched
	}
}

public class UserService
{
	public User GetUser(Guid userId)
	{
		_accessService.ValidateAccess(AccessType.Read, DataType.User, userId)

		var userModel = _userRepository.GetUser(userId);
		var userData = _userDataRepository.GetUserData(userId);
		var salaryData = _userSalaryRespository.GetUserSalaryData(userId);

		var user = _mapper.Map<User>(userModel, userData, salaryData);

		_eventLogger.Log(EventLogType.GetUser)
		
		return user;
	}
}

Sen har ju kommentarer sin plats också - Jag tänkte vi kunde kolla på CyberVillans kodexempel på en till mesta delen utmärkt kod, man fattar ju direkt vad koden ska göra, men inte riktigt effekten av den - Mina kommentarer för att illustrera, kanske.

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

// Composition over inheritance? - Food for thought!
public class TubeFedShotgun : InternalMagazineFirearm
{
	protected override void Awake()
	{
		base.Awake();
		// Immutable instead and from ctor?
		Category = FirearmCategories.Primary;
		UsesTouchpad = true;
	}

	public override bool TriggerReady(NVRButtonInputs trigger)
	{
		// Attach trigger as an injection on ctor?
		return trigger.SingleAxisDown;
	}
	
	protected override void AddForceToCasing(Rigidbody casing)
	{
		// Here we are adding force to the left? and divide it by 
		// some arbitrary number because of reasons
		casing.AddForce(-this.transform.right * 1.5f);
		// Applying more physics using arbitrary numbers and we 
		// have no real idea why they are what they are
		//
		// Moving these numbers into variables and even a method in 
		//itself for the vector, might help explain why the numbers 
		// in question are what they are
		casing.AddRelativeTorque(new Vector3(0.0005f, 0.001f * (5 + Random.value * 5), 0.0005f));
	}
}

Att inte ha läst Robert Martin och jobba som programmerare är som att spela farmville på facebook och kalla sig gamer. Jag jobbar med miljoner rader kod, jag skiter i om du kan nya syntaxen för C# 7.2. Om din kod behöver kommentarer för att kunna förstås om 6 månader ligger du pyrt till. (Sen ska du givetvis också kunna nya C# 7.2 syntaxen, något annat vore ju tjänstefel! EHEH).

Näe grabbar, sluta jiddra och börja läsa mer böcker, sen applicerar man vad gudarna har kommit fram till, och gör om, gör rätt, varje dag, tills polletten trillar ner. 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.

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.

Kanske om ni hade kommenterat koden hade ni inte haft så många fuckups Skämt å sido.

Håller helt med om att man nästan aldrig behöver kommentarer; dock skulle jag inte påstå att git meddelandena var särskilt beskrivande heller av vad som ändrats. "Fixat en fuckup". Jaha; vad var det som var fel då? ^^

Men spelet ni skapat ser intressant ut!

Att säga att kommentarer är onödiga och att koden ska vara självförklarande låter väldigt bra, men är i praktiken att skjuta sig själv i foten.

Varför då?

Jo för att alla har en tendens att tro att de är duktigare än vad de är, så att sprida en sådan attityd kommer uppmuntra otaliga oskickliga programmerare att inte kommentera sin kod.
Du kommer garanterat få sådan kod på ditt bord förr eller senare, och risken är stor att det blir du som måste traggla igenom dess trassliga garnnystan för en refaktorisering.

Så visst kanske jag kan hålla med dig i en teoretisk värld där alla programmerare faktiskt kan skriva bra och självdokumenterande kod, men vi vet alla att det tyvärr inte är så verkligheten ser ut.

Så gör dig själv en tjänst, genom att inte be folk att inte kommentera sin kod, utan istället skriva ett litet banalt script som kan rensa bort alla kommentarer/brus ur en kod-fil. Superenkelt, och du får det bästa av två världar om nu kommentarerna stör eller förvirrar. Att drömma om att all kod som landar i knät är bra kod, eller att folk genuint blir bättre programmerare bara för att man säger till dem "skriv bättre kod med färre kommentarer", kommer bara leda till mer smärta.

För i verkligheten är ju argumentet precis så dumt; det är ju ingen som säger "skriv sämre kod", oavsett vad ens ställning till kommentarer är, och syftet för dem som propagerar mindre kommentarer tycks ju mest vara att de vill slippa få dålig kod av andra. Det är ni inte ensamma om, men då argumentet bygger på "om folk skrev bättre kod istället för..." så är det bara en dröm med ett väldigt stort om.

Det blev visst en lite aggressiv ton på texten tycker jag, fast det var inte meningen, har bara en stark åsikt i frågan.

Mycket har redan sagts här, min uppfattning är att kommentarer i en kodbas är givetvis en bra sak. Din kod säger hur du löste problemet (eventuellt löste, för vi vet ju alla att just din egen kod är 100% korrekt!) medan en kommentar kan förklara din intention med koden. Och just intention är värt mycket.

Sen måste jag säga CyberVillain, du må vara en kompetent programmerare men jag hade antagligen inte velat jobba med dig eller din okommenterade kod. När jag läser dina inlägg här i tråden ger du mig intrycket av att vara en dålig teamplayer. Blir så trött på hela den här inställningen "only stupid people don't understand my code" och att sen att skriva att folk borde få sparken etc etc, nej, har jobbat med ett par sådana konsulter och det är fan drygt. Inget personligt CyberVillain, bara min uppfattning, kan ha helt fel, who knows..

Så gör dig själv och dina kollegor en tjänst och kommentera din intention med koden när det behövs eftersom programmering är en team effort.