Forum Mjukvara Programmering och digitalt skapande Tråd Inlägg

Konsten att kommentera?

1
Skriv svar
Permalänk
Medlem ★
●

Konsten att kommentera?

Efter min lärare halshuggit mig ytterligare en gång och denna gången angående hur jag kommenterar mitt program så undrar jag hur ni brukar bära er åt.

Själv så har jag alltid bara haft en kort beskrivning av vad metoden/programmet gör samt in och ut-parametrar. I koden har jag aldrig kommentarer utan istället försöker jag programmera en kod som förklarar sig själv.

Hur gör ni?

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Är av åsikten att kommentarer inte ska behövas. Kommenterar normalt bara om det är något som är väldigt komplicerat eller på annat sätt otydligt. Med bra namnsättning av metoder och variabler så är kommentarer oftast överflödiga.

Visa signatur

He who hasn't hacked assembly language as a youth has no heart. He who does so as an adult has no brain.
~John Moore

Redigera
Citera flera Citera
Permalänk
Hjälpsam ★
●

Har sett hur många gånger som helst kod i företagssystem som blir mer eller mindre obrukbart efter att en person har lämnat företaget. Dokumentering och kommentarer för tydlig överblick för andra som ska behöver harva i koden för att lägga till eller justera moduler och parametrar. Bättre att ta för vana från början att göra det strukturerat.

Visa signatur

Allt jag säger/skriver här är mina egna åsikter och är inte relaterade till någon organisation eller arbetsgivare.

Jag är en Professionell Nörd - Mina unboxing och produkttester (Youtube)
Om du mot förmodan vill lyssna på mig - Galleri min 800D med 570 Phantom SLI

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Vet inte hur mycket tid vi lägger på att förstå odokumenterad kod...

Bara för att du tycker att koden förklarar sig själv kanske inte någon annan gör det.

Dessutom, att man förstår vad koden gör innebär inte att man förstår varför den gör så.

Te x försöker jag få reda på varför en bit kod ändrar ett värde under vissa förutsättningar för det är inte logiskt att göra det. Förmodligen är det en workaround på hur något i källsystemet fungerar men ingen har kunnat bekräfta det.

Visa signatur

"When I get sad, I stop being sad and be awsome instead, true story."

Redigera
Citera flera Citera
Permalänk
99:e percentilen ★
●

Detta är ett svårt ämne med mycket starka subjektiva inslag.

Jag tycker det är bra att tänka på följande:

  • Kommentarer ska inte vara en kopia av koden. Ser ofta nybörjare kommentera likt följande:

    int i = 0; // Skapa variabeln i och sätt den till 0.

    Detta gör mer skada än nytta, åtminstone när man kommit förbi nybörjarstadiet.

  • Kommentarer innefattas, liksom kod, av DRY – det är aldrig fördelaktigt att behöva komma ihåg att ändra på flera ställen – men kommentarer är i regel svårare att hålla DRY än vad kod är. Kompilatorn kan ju inte hjälpa till.

  • Det är viktigt med kommentarer när det inte är självklart varför koden ser ut som den gör. prevent-accidental-unload.ts i Better SweClockers är ett bra exempel på detta, med ett flertal kommentarer som i princip är nödvändiga (även för mig!) för att förstå varför koden är skriven som den är.

Senast redigerat La till länk till Wikipedia-artikeln om DRY.
Visa signatur

Skrivet med hjälp av Better SweClockers

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Min tanke med programmering och kommentarer är att man skriver kommentarer för att motivera varför man gjort något. Jag tycker man ska förutsätta att personen som kommer läsa koden kan språket och att man därmed inte behöver förklara vad koden gör.

Som ett exempel kan man ta koden nedan. (Jag mellanlagrar state för tydlighets skull, vi behöver inte lägga tid på att diskutera fler konventioner.)

state = check_something()
if state:
  disable_thing()

Det är totalt värdelöst att lägga en kommentar likt denna:

# Check someting and if state is true we disable the thing.
state = check_something()
if state:
  disable_thing()

Medans följande kommentar är väldigt vettig, imho:

# check_something returns true iff something is in state C
# this will cause thing to crash (see documentation in disable_thing() for more info)
# hence we must disable thing before proceeding 
state = check_something()
if state:
  disable_thing()
Visa signatur

:(){ :|:& };:

🏊🏻‍♂️   🚴🏻‍♂️   🏃🏻‍♂️   ☕

Får det lov att vara en kaffe?

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Sluta tänk själviskt och fundera istället hur en kodare utan större erfarenhet ska kunna lista ut ditt lilla språk eller system. Det är väldigt lätt att tycka en sak vara självklar, men precis som politiska åsikter kommer ingen fatta det minsta om du inte är väldigt tydlig, saklig, och noggrann.

Att förklara vad en sak gör berättar inte nödvändigtvis hur den ska tillämpas. Det berättar heller inte varför eller hur den gör det den gör, utan det är fortfarande bara en massa hieroglyfer som återfyller din HP.

Din lärare bör ha givit dig något mer än bara skäll. Om inte är det kanske på sin plats att fråga läraren vad man bör tänka på, hur man ska tillämpa kommentarer, och om det finns särskilda infallsvinklar man bör ha.

Ingen har automatisk telepati. Det har vi däremot genom skrift, men då måste man formulera sig väl.

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Kör efter MISRA i många fall. Kan bli förbaskat jobbigt om man avviker och inte har kommenterat korrekt enligt ramverket man använder.

https://en.wikipedia.org/wiki/MISRA_C

Visa signatur

MSI K9N SLI Diamond | MSI Diamond HDMI 7600GT | AMD X2 4200+ | 1GB Kingston HyperX| 32" LG 5000:1 screen | Asus EeePC 701

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Kod som inte är glasklart uppenbar för "alla" ska alltid kommenteras. Ju mindre uppenbart desto viktigare med utförlig och begriplig kommentering.

Vi har ett par nötter här på jobbet som anser att koden ÄR dokumentationen, och kommenterar i princip aldrig. Gissa vilken kod alla vi andra sedan har problem att tolka?

Allra värst är utvecklare som är självlärda, de lever ofta i sin egen lilla värld med udda lösningar på problem som inte är kommenterade alls.

Visa signatur

5950X, 3090

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

@Json_81: Det är ett typiskt exempel på när kommentarer är bra och viktiga.

Visa signatur

He who hasn't hacked assembly language as a youth has no heart. He who does so as an adult has no brain.
~John Moore

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Jag har läst programmering i 3 månader så ingen expert. Jag tänker på detta problemet ungefär som ett klurigt spel med mycket info i, typ Witcher 3, Divinity Orignal Sin 2, Warframe, Diablo 3. Alla dessa spel har ju alla stats "synligt", vem som helst kan ju läsa statsen och förstå. Ditt jobb är att starta spelet du aldrig spelat tidigare och göra den "optimala" karaktären. Statsen förklarar ju sig själva eller hur? Du behöver bara sätta dig och lägga en 40-50h för att komma fram till hur spelet fungerar (koden hänger ihop). Alternativt så kan du läsa en walkthrough (kommentarerna) som snabbt och smidigt förklarar hur du optimerar (hur din kod fungerar) och du kan göra exakt samma jobb på 30 minuter.

När du börjar arbeta med program med flera användare och miljontals rader kod så kommer dina walkthroughs vara avgörande för hur mycket tid dina kollegor behöver lägga på att förstå vad du gör i din kod. Det är inte det att de kan utan kommentarer, det är bara löjligt mycket mer effektivt att läsa en kommentar.

Redigera
Citera flera Citera
Permalänk
Avstängd
●

Nu är jag ingen programmerare i sig (kan skapa "Hello World!" i C++ samt använda cin och cout). Skriptar i AutoHotKey.

Grundläggande "programmeringsgrammatik" som att veta när något beskriver att en datatyp definieras (eller en hel struct av datatyper), en funktion(){} skrivs ut, if- och loop-satser, sådant tycker jag inte skall behöva kommenteras för det förutsätts att nästa kodare skall förstå.

Däremot bör det kommenteras HUR "grammatiken" används i form av "stil", typ om koden som skrivs är skriven främst för optimering, eller om den är skriven för främst att vara modulär (så du kan ändra en del utan att allt annat fallerar), om det är tänkt att vara någon variant av objektorienterad programmering (och inte möjligen den OOB som beskrivs i läroböcker), om det är genetisk kod, osv.,

Varje större och utskriven function() bör ju få en kommentar om vad den gör och om den kallar på någon annan function() i någon annan fil eller i samma fil för att lättare kunna följa exekveringsflödet för koden. Just kommenterar som hjälper en att följa exekveringsflödet för koden låter väl vettigt? Jag är som sagt var ingen programmerare så jag kanske bara sa massa "dynga" nu!

Visa signatur

"Företagsboendeförmedlare" | Min Überkill Dator: Processor: Intel Pentium P5 66 Mhz OC | Moderkort: ASRock P4I65G | Minnen: 2st Samsung 128MB PC133 | Grafikkort: Canopus GeForce 256 DDR | Lagring: IBM 350 4,4 MB | Operativsystem: DOS/360 | Chassi: Mercury Full-Tower ATX Chassis |

Redigera
Citera flera Citera
Permalänk
Inaktiv
●

Jag dokumenterar på tre nivåer:

Den första är en design-logg med bakgrunder och diskussioner runt olika designbeslut som togs under uppbyggnaden av koden. Den här är den viktigaste dokumentationen. Läs det dokumentet och du kan mer av det som spelar roll än den som skrev koden.

Den andra nivån är ett dokument som innebär en karta över de olika delarna och grovt vad de gör. Syftet här är att minska tiden för en ny att sätta sig in i koden. Gör också att man behåller överblicken över kodbasen.

Tredje nivån är förklaringar av knepiga detaljer inne i koden. Det är bara denna nivån som finns inuti koden.

Den klassiska nivån med att förklara in/ut-parametrar brukar jag slarva med. Det brukar framgå ändå med bra och förklarande namn på variabler och metoder etc. och om koden verkligen är väl strukturerad. Att hålla namnen bra och förklarande, och strukturen ren, brukar innebära en hel del refactoring under arbetets gång men med dagens verktyg så går det fort och exakt.

Den som tror att man klarar sig utan dokumentation skall inte sättas på att göra något som är det minsta icke-trivialt. Enklast är att bara leda ut vederbörande ur byggnaden, fram till någon lekplats i någon park. Inget tålamod alls med den attityden. En barnrumpa.

Senast redigerat
Redigera
Citera flera Citera
Permalänk
Medlem
●

Ytterst sällan kommentera! Namn långa och beskrivande. Håll dem gärna i ett centralt "Data Dictionary" för hela företaget. Ha alltid ett huvud i varje program del som förklarar funktion och argument. Slösa inte på rader. Måsvingar {} skall ICKE ha egna rader! Eftersom block sowieso har indentering.
Exempel:
inflation_high=inlation>4;
inflation_low=inflation<2;
if(inflation_high){
___ sell(stocks);
___ buy(gold);}
if(inflation_low)sell(gold);
return;

Redigera
Citera flera Citera
Permalänk
Medlem
●
Skrivet av anon214822:

Jag dokumenterar på tre nivåer:

Den första är en design-logg med bakgrunder och diskussioner runt olika designbeslut som togs under uppbyggnaden av koden. Den här är den viktigaste dokumentationen. Läs det dokumentet och du kan mer av det som spelar roll än den som skrev koden.

Den andra nivån är ett dokument som innebär en karta över de olika delarna och grovt vad de gör. Syftet här är att minska tiden för en ny att sätta sig in i koden. Gör också att man behåller överblicken över kodbasen.

Tredje nivån är förklaringar av knepiga detaljer inne i koden. Det är bara denna nivån som finns inuti koden.

Den klassiska nivån med att förklara in/ut-parametrar brukar jag slarva med. Det brukar framgå ändå med bra och förklarande namn på variabler och metoder etc. och om koden verkligen är väl strukturerad. Att hålla namnen bra och förklarande, och strukturen ren, brukar innebära en hel del refactoring under arbetets gång men med dagens verktyg så går det fort och exakt.

Den som tror att man klarar sig utan dokumentation skall inte sättas på att göra något som är det minsta icke-trivialt. Enklast är att bara leda ut vederbörande ur byggnaden, fram till någon lekplats i någon park. Inget tålamod alls med den attityden. En barnrumpa.

Gå till inlägget

Bra. Kreativ programutveckling är och måste ofta vara en iterativ process. Där det är viktigt att kod och tillhörande dokument utvecklas parallellt. Jag har varit med om överbetalda konsulter som i stort sätt vägrade dokumentera. Men det värsta är dumma chefer som tror att man kan köpa nyckelfärdiga system.

Redigera
Citera flera Citera
Permalänk
Medlem ★
●
Skrivet av Fluf:

Har sett hur många gånger som helst kod i företagssystem som blir mer eller mindre obrukbart efter att en person har lämnat företaget. Dokumentering och kommentarer för tydlig överblick för andra som ska behöver harva i koden för att lägga till eller justera moduler och parametrar. Bättre att ta för vana från början att göra det strukturerat.

Gå till inlägget

Har grävt i kod som är skriven av "experter" och det är ett detektivarbete varje gång att leta reda på saker eftersom kommentarer är sällsyntare än guld. De som finns är ofta värdelösa, vem som skrev det vid vilken tidpunkt när programmet kommer från ett helt annat team ger precis noll. Andra icke-givande kommentarer är typ "vi fixar detta för att lösa ett problem med kompatibiliteten" (vad är "detta" och för vilken kompatibilitet?), eller före en while på en array "Vi loopar igenom arrayen och sätter variablerna" (Jepp! Jag ser det, men vad är syftet med vad de sätts till? Finns det något som inte får matas in?). Har dessutom en backlog på olösta buggar som är ett mysterium (bara det i sig gör att en kan fråga sig hur de kunde kalla sig experter). Självklart så är de inte olösbara, då det ibland spontant när andra buggar söks, hittas orsaken till varför en av mysteriebuggarna i sig själv uppstod, vilket leder till att det går att formulera en lösning på problemet. Riktiga kommentarer, som beskrivet av flera här i tråden, skulle ha gjort arbetet oändligt många gånger enklare, då det förmodligen skulle gjort att det funnits möjlighet att finna lösningar på problemen istället för att de skulle hamnat i en backlog som ett olöst mysterium.

Skrivet av anon214822:

Jag dokumenterar på tre nivåer:

Den första är en design-logg med bakgrunder och diskussioner runt olika designbeslut som togs under uppbyggnaden av koden. Den här är den viktigaste dokumentationen. Läs det dokumentet och du kan mer av det som spelar roll än den som skrev koden.

Den andra nivån är ett dokument som innebär en karta över de olika delarna och grovt vad de gör. Syftet här är att minska tiden för en ny att sätta sig in i koden. Gör också att man behåller överblicken över kodbasen.

Tredje nivån är förklaringar av knepiga detaljer inne i koden. Det är bara denna nivån som finns inuti koden.

Den klassiska nivån med att förklara in/ut-parametrar brukar jag slarva med. Det brukar framgå ändå med bra och förklarande namn på variabler och metoder etc. och om koden verkligen är väl strukturerad. Att hålla namnen bra och förklarande, och strukturen ren, brukar innebära en hel del refactoring under arbetets gång men med dagens verktyg så går det fort och exakt.

Den som tror att man klarar sig utan dokumentation skall inte sättas på att göra något som är det minsta icke-trivialt. Enklast är att bara leda ut vederbörande ur byggnaden, fram till någon lekplats i någon park. Inget tålamod alls med den attityden. En barnrumpa.

Gå till inlägget

Wow, vilket bra sätt att kommentera/dokumentera! Är visserligen självlärd men tar god programmering på stort allvar och ska definitivt ha med detta i bakhuvudet inför framtiden. Flernivådokumentering...

En av de svåraste sakerna jag insett med programmering är att göra kod/kommentarer så att andra begriper, inte att formulera komplicerad programkod i sig. God programmering tar tid att lära sig och framför allt ett öppet sinne är guld värt.

Det är sällan som en faktiskt kommer i kontakt med saker som kräver extrem programoptimering, det sköter redan de flesta kompilatorer utmärkt. Speciellt i de fallen så är god kommentering utomordentligt viktigt, eftersom även du kommer ha svårt att felsöka din egen komplicerade kod senare.

Redigera
Citera flera Citera
Permalänk
Medlem
●

Om man menar kommentarer i kod så tycker jag det är viktigast att fokusera på vad din kommentar har för nytta i koden. Precis som flera redan har nämnt är det för mig helt onödigt att kommentera VAD din kod gör, det som är intressant för en som läser din kod är VARFÖR den gör som den gör.
Om man känner att man måste lägga in en kommentar som förklarar VAD ens kod gör så bör man nog fundera på om man inte kan beskriva det på ett bättre sätt, förslagsvis genom att använda bättre namn på klasser/funktioner/variabler. Med detta i åtanke brukar jag ytterst sällan kommentera i koden över huvud taget. Undantagsfallet här skulle vara ifall jag behöver göra nån väldigt konstig work-around runt ett externt bibliotek eller liknande som jag inte har kontroll över. Då kan det vara bra att skriva några ord om varför jag gör en så konstig sak så att den som kommer efter (eller jag själv för den delen) inte råkar förstöra nåt senare.

Om man menar kommentarer som dokumentation för funktioner/metoder som beskriver vad en funktion gör, samt in- och utparametrar så skriver jag endast dessa för funktioner som kommer användas publikt av andra tjänster. Annars försöker jag (precis som jag skrev ovan) att hålla mig till bra namnkonventioner, då dessa förklarar koden på ett mycket bättre sätt. Det är även lättare att underhålla kod än kommentarer. Kommentarer blir väldigt lätt utdaterade.

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Kommenterar så mycket som jag tror ska behövas för att någon annan ska förstå + en del extra eftersom vi människor är dåliga på perspektivtagande och alltid tror att andra tänker mer likt oss själva än vad de gör.

I slutändan kan det ändå vara så att jag själv inte förstår koden efter ett år, men det händer mer och mer sällan.

Visa signatur

Här hade jag en historik sen 1990-talet, men den blev tillslut för lång. Aktiva maskiner 2022-framåt:
Work/Play/Everythingstation: AMD Epyc 7443p, Pop OS host, Win10 + Linux guests (KVM/Qemu)
Work/Play nr 2: AMD Phenom II 1090t, Debian + Win 10 (dual boot)
Server x3: Epyc 7252 (TrueNAS Core), Atom 2550 (FreeBSD, backup), Opteron 6140 (Ubuntu, off prem backup)
Retrohörna under uppbyggnad: Dual Pentium Pro 200MHz, Pentium P54C 90MHz, Gravis Ultrasound MAX

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Det är en meme, men jag tänker när jag skriver koden "ah men det här är ju ganska uppenbart vad som händer", och sen kommer jag tillbaka några månader senare och tänker "hur fan tänkte jag det här?".
Men sen när jag väl kommenterar jag tycker jag att jag kommenterar för mycket.
Det är knepigt.

Visa signatur

13600KF, RTX 4070 FE, B760I, 32GB DDR4, NR200P

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Märker själv om jag kodat en hemsida och sen måste tillbaka till den några år senare för att fixa något.. förstår inte min egna kod.

Skickades från m.sweclockers.com

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Får flashbacks till denna tråd:
https://www.sweclockers.com/forum/trad/1505351-kommentarer-ar...

Där finns mycket att läsa!

Fram med chipspåsen!

Visa signatur

[IT-Dept]
Ryzen 1700 OC - 32 - 1070

Redigera
Citera flera Citera
Permalänk
Medlem ★
●

Kommentera där det behövs, annars ska koden tala för sig själv. En kommentar innebär mer saker att förvalta, ändrar man koden måste man ändra kommentaren, annars kommer den ge falsk information.

Jag tenderar att kommentera i ytterst få tillfällen, oftast där jag gör externa anrop och behöver sammanfatta funktionen för det inte går att följa flödet.

Men annars skriver jag hellre långa variabel- och metodnamn.

I skolan skulle man alltid kommentera överflödigt, men det handlade snarare om att man skulle förstå vad som sker i sin kod.
Däremot kanske man inte ska skriva, här loopar jag. Utan istället, här loopar jag igenom min lista av X för att göra Y.

Skickades från m.sweclockers.com

Senast redigerat
Redigera
Citera flera Citera
Permalänk
Medlem
●

Jag har alltid sett de flesta kommentarer som en brist på programmeringsförmåga. Strukturerar man sin kod ordentligt ska det behövas minimalt med kommentarer för att en annan programmerare (eller du själv i framtiden) ska förstå vad koden gör.

Mitt råd är därför att man delar upp längre, komplicerade kodstycken i flertalet enklare funktioner snarare än att infoga kommentarer överallt. Alla identifierare (funktionsnamn, typnamn, namn på parametrar, konstanter, variabler och liknande) bör ges namn som korrekt beskriver vad de representerar. Längre, komplicerade rader bör även delas upp i fler men enklare rader.

Kommentarer bör självfallet lämnas i vissa fall. Ett exempel är när man fastnar på något som inte fungerar som det ska. Fastnar man är sannolikheten att någon annan också gör det sannolikt hög och man bör därför lämna en kommentar.

Om kommentarer används som dokumentation rekommenderar jag att man istället skriver tester som säkerställer funktionaliteten samtidigt som den dokumenteras.

Skickades från m.sweclockers.com

Redigera
Citera flera Citera
Permalänk
Medlem
●

För mig beror det mycket på hur stabil kodbasen är. Om ändringar är regelbundna föredrar jag färre kommentarer till förmån för simplare satser, mer beskrivande variabelnamn, och mer uppdelning i separata funktioner. Detta kan innebära mer jobb på kort sikt, och koden blir lite mindre elegant, men man slipper kommentarer som är svåra att underhålla i en instabil kodbas, men koden är lättförståelig ändå.

Det motsatta scenariet är att koden är överlag immuterbar — i.e. den skrivs en gång, men läses mycket. Exempel på sådana program är de i e.g. forskningspapers. Här föredrar jag att använda literate programming för att beskriva den korta men avancerade koden i utförlig prosa, och ha en enda fil som är både programmet och rapporten i ett. Jupyter notebooks är ett liknande koncept, för dem som känner till det.

Ett exempel på literate programming är Physically Based Rendering (PBR) Book. Detta projekt kan både betraktas som ett extremt utbildande och utförligt dokumenterat program, eller som en bok vars kodexempel är typcheckade och garanterat kompilerbara till ett fungerande program tillsammans.

Senast redigerat
Visa signatur

Arbets- / Spelstation: Arch Linux - Ryzen 5 3600 - RX 7900 XT - 32G DDR4
Server: Arch Linux - Core i5-10400F - 16G DDR4

Redigera
Citera flera Citera
1
Skriv svar
Senaste nyheterna
Hårdvara
Mjukvara
Övrigt
Nytt i forumet
Datorkomponenter
System
Ljud, bild och kommunikation
Spel och mjukvara