Vinnaren i pepparkakshustävlingen!
  • 1
  • 2
2017-07-11, 08:17
  #1
Medlem
Voldemort2s avatar
Ja, hur kommenterar man egentligen på bästa sätt. Hur mycket skall man kommentera och hur är det bäst att strukturera detta? Är det någon som har någon bra idé angående detta?
Citera
2017-07-11, 10:17
  #2
Medlem
kimdah2002s avatar
Det bästa sättet enligt min erfarenhet är
1. Använd begripliga och beskrivande namn på variabler, funktioner, procedurer m.m. utarbeta en standard och följ den.

2. Skriv inte mer kod än att det går att läsa på 1-2 skärmsidor, försök att dela upp den om den blir för lång i moduler och kommentera varje modul för sig.

3. Skriv inte onödiga kommentarer i koden utan variabelnamnen skall vara självdokumenterande, behöver t.ex. en beräkning kommenteras skriv några rader innan avsnittet.

4. Skriv inte för långa kodrader utan gör radbrytningar så det blir lättläst

5. Lämna mellanrum mellan kodavsnitt

6. Gör korrekt indentering av satser och funktioner m.m.

7. Skriv enkel kod
Citera
2017-07-11, 10:33
  #3
Moderator
Protons avatar
Citat:
Ursprungligen postat av Voldemort2
Ja, hur kommenterar man egentligen på bästa sätt. Hur mycket skall man kommentera och hur är det bäst att strukturera detta? Är det någon som har någon bra idé angående detta?
I mitt tycke beror det även lite granna på vad det är man vill koda med.

Är det nåt slags classlib man kodar ihop kan det ju vara värt att använda javadoc, för att få schyssta beskrivningar etc i diverse editors, detta är dock i min mening endast relevant om man ska leverera kompilerade klasslibbar och inte källkod. Är det källkod kan imo javadoc vara mer i vägen än till nytta, speciellt om det är kod som kan tänkas ändras ofta.

Gäller det "normal" källkod har nån redan sagt det, men kod som är självkommenterande är ju det bästa (dvs vettiga variabelnamn på saker och ting), annars kan man ju lägga en kommentar här och där när man gör något extra halsbrytande, eller där det kanske inte är alldeles uppenbart för alla varför man gjort på det ena eller det andra sättet.
Citera
2017-07-11, 17:19
  #4
Medlem
Som de har sagt, plus att det inte behövs många kommentarer överallt. Har du en funktion som beräknar o lägger ihop lite grejer, skriv in en kommentar för varje steg, det räcker med att ha en kommentar som förklarar, är funktionsnamnet redan förklarade behövs kommentaren än mindre.

Ett annat sätt att kommentera är att använda klassnamn och lagra dem på varandra. Vet dock inte om det går i java då jag inte lekt med det på ett bra tag. Men fungerar bra på statiska grejer, t.ex. File.Download.FromFTP(etc), File.Download.FromDisc(etc), File.Upload.ToFTP(etc) osv.
__________________
Senast redigerad av Gottisborgen 2017-07-11 kl. 17:21.
Citera
2017-07-12, 08:11
  #5
Medlem
Voldemort2s avatar
Tack för era synpunkter. Kommentarer sker alltså både före metoderna och i metoderna i de fall som detta krävs, men genom att sätta bra variabelnamn och dylikt så minimeras dess kommentarer.
Citera
2017-07-12, 09:03
  #6
Moderator
Protons avatar
Citat:
Ursprungligen postat av Voldemort2
Tack för era synpunkter. Kommentarer sker alltså både före metoderna och i metoderna i de fall som detta krävs, men genom att sätta bra variabelnamn och dylikt så minimeras dess kommentarer.
Ja det är väl en bra sammanfattning.

Man behöver inte kommentera varenda if som finns, men däremot kan det ju vara värt att i if-blocket skriva en rad om vad som ska hända om villkoret uppfylls, typ såhär:

Kod:
if(payment.getState() == PaymentState.UNPAID){
//send notification of unpaid payment.
sendUnpaidMail();


Ren improviserad kod, men du förstår prncipen iaf. iffen kan jag läsa själv vad den jämför, men däremot är det alltså vettigt att skriva en rad om vad koden gör om villkoret uppfylls.
Citera
2017-07-14, 04:09
  #7
Medlem
UlphSvensons avatar
Kommentarer som inte är API (typ Javadoc) och därmed menade att ingå i dokumentation är endast i undantagsfall inte ett misslyckande, det ska vara nåt jävligt märkligt fall där inte metodnamn med parameternamn kan förklara exakt vad som sker/ska ske. I alla fall i ett högnivåspråk (vilket är typ assembler med labels och uppåt, i det här fallet). Och finns det inget bra namn som passar, ja då är det dags att bryta isär och refactorera.

Citat:
Ursprungligen postat av Proton
Ja det är väl en bra sammanfattning.

Man behöver inte kommentera varenda if som finns, men däremot kan det ju vara värt att i if-blocket skriva en rad om vad som ska hända om villkoret uppfylls, typ såhär:

Kod:
if(payment.getState() == PaymentState.UNPAID){
//send notification of unpaid payment.
sendUnpaidMail();


Ren improviserad kod, men du förstår prncipen iaf. iffen kan jag läsa själv vad den jämför, men däremot är det alltså vettigt att skriva en rad om vad koden gör om villkoret uppfylls.

Om inte sendUnpaidMail() förklarar bra nog vad som händer i sig självt så kanske metoden ska heta sendNotificationOfUnpaidPayment() och vips är kommentaren 100% redundant. Är det av ngn anledning viktigt att veta att det är mail också kan man alltid slänga in det någonstans: sendNotificationEmailOfUnpaidPayment()

Än värre är att kommentarer så ofta ljuger. Metoden kanske gjorde vad kommentaren säger för tre år sen, men nånstans ändrades logiken men inte kommentaren, det råkar man på precis hela tiden. Som yrkesprogrammerare tillbringar man ofta 95% av tiden med att läsa kod, inte skriva, och den bästa koden är den som är så lättläst att den är självdokumenterande. Kommentarer är i bästa fall i vägen, i sämsta fall villospår.

När man börjar koda så strör man ofta kommentarer i koden för sin egen skull, för att hjälpa tankeverksamheten och hålla reda på vad man håller på med - det är helt fine! Men så fort man börjar få lite koll är det dags att vänja sig av med det och istället skärpa till koden.

Samtidigt, bra namn och ändå kommenterat är tusen ggr bättre än dåliga namn och inga kommentarer. Så det är inte längst ner på stegen
__________________
Senast redigerad av UlphSvenson 2017-07-14 kl. 04:10. Anledning: +inte
Citera
2017-07-14, 04:12
  #8
Medlem
UlphSvensons avatar
Citat:
Ursprungligen postat av Voldemort2
Ja, hur kommenterar man egentligen på bästa sätt.

TL;DR: inte alls.
Citera
2017-07-31, 08:38
  #9
Medlem
Om du döper klasser, variabler och metoder korrekt behöver du inte kommentera alls. Som någon nämnde innan så kan det vara bra med javadoc om du skapar class library, men även där så ska du döpa allt korrekt. Att jobba som kodapa innebär att 10% av tiden går åt till att skriva kod, 50% av tiden till att planera koden man ska skriva och 40% går åt till att komma på ett bra namn till en metod eller variabel.
Citera
2017-08-02, 03:51
  #10
Medlem
UlphSvensons avatar
Citat:
Ursprungligen postat av mickes418
Om du döper klasser, variabler och metoder korrekt behöver du inte kommentera alls. Som någon nämnde innan så kan det vara bra med javadoc om du skapar class library, men även där så ska du döpa allt korrekt. Att jobba som kodapa innebär att 10% av tiden går åt till att skriva kod, 50% av tiden till att planera koden man ska skriva och 40% går åt till att komma på ett bra namn till en metod eller variabel.

Står fast vid att "jobba som kodapa" består till absolut största delen av att läsa kod, oftast skrivet av nån jävla amatöridiot som inte sällan visar sig vara du själv för sex månader sen. Nån sa nån gång att man ska skriva sin kod som om den som ska förvalta den är en våldsam psykopat som vet var du bor, well hint, det är ofta du som kommer förvalta den, psykopat eller inte, så det är bara att göra sig själv en tjänst direkt.

Varje gång du kommer tillbaka till din egen kod och inte förstår vad den snutten gör utan kommentarer, eller nästa gång du hittar kommenterad kod som inte gör vad kommentaren en gång sa, remember this thread.
Citera
2017-08-02, 03:54
  #11
Medlem
UlphSvensons avatar
Kan kanske vara tydligare med också att Javadoc (och motsvarigheter i andra språk) är till för att generera API-dokumentation och eventuellt ge autocomplete-hints i kompetenta IDE:er, så det är lite av ett specialfall. Kan gott hjälpa även för den som sitter och hamrar i en texteditor som känner igen vilka ord man redan använt, också, såklart.
Citera
2017-09-12, 10:30
  #12
Medlem
Ju mindre kommentarer du behöver desto bättre. Behöver du kommentera så är det troligvis du som har misslyckats med programmerandet. Din kod är så jävla dålig att du måste förklara med ord vad den gör.
__________________
Senast redigerad av delernen 2017-09-12 kl. 10:33.
Citera
  • 1
  • 2

Stöd Flashback

Flashback finansieras genom donationer från våra medlemmar och besökare. Det är med hjälp av dig vi kan fortsätta erbjuda en fri samhällsdebatt. Tack för ditt stöd!

Stöd Flashback