Tanker rundt kodestandard / programming guidelines

[steingrim]

Nå fikk jeg redigert innlegget mitt og skrevet det ferdig

 

Edit: var ikke meninga å ødelegge for alle andre!

Endret 3. mars 2010 av steingrim

[tomsi42]

Her tar jo den totalt unødvendige javadoc-kommentaren dobbelt så mye plass som metoden. Og grunnen til at jeg irritererer meg er selvsagt at jeg skjønner jævlig godt hva setFoo() gjør. Det er nettopp når den gjør noe ekstraordinært det er verdt å kommentere. Som sagt, jeg nappa ut 8000 slike linjer i et prosjekt på jobben. Det var deilig

Jeg er enig i at slike kommentarer er bare fjas. Men noen av disse attributtene trenger innimellom en beskrivelse. Hvordan dokumenterer du de?

[steingrim]

Jeg er enig i at slike kommentarer er bare fjas. Men noen av disse attributtene trenger innimellom en beskrivelse. Hvordan dokumenterer du de?

Jeg synes ikke ordinære get/set-metoder trenger å dokumenteres i det hele tatt.

[GeirGrusom]

Jeg hater utsagn som dette:

/// <summary> Gets or sets the name of the student</summary>
public string Name { get { return name; } set { name = value; } }

Hva er poenget? Det eneste nyttige som kommer frem, er at egenskapen er read/write.

.NET er forøvrig fullt av det.

[tomsi42]

Jeg er enig i at slike kommentarer er bare fjas. Men noen av disse attributtene trenger innimellom en beskrivelse. Hvordan dokumenterer du de?

Jeg synes ikke ordinære get/set-metoder trenger å dokumenteres i det hele tatt.

 

Jeg hater utsagn som dette:

/// <summary> Gets or sets the name of the student</summary>
public string Name { get { return name; } set { name = value; } }

Hva er poenget? Det eneste nyttige som kommer frem, er at egenskapen er read/write.

.NET er forøvrig fullt av det.

 

Det er situasjoner hvor en property trenger en liten beskrivelse(ikke ofte, men det skjer), og i java så har man ingen umiddelbar kobling mellom den private variablen og setter/getter.

 

Hvor skal man da dokumentere?

[Jann - Ove]

Selvdokumenterende kode bør være en prioritet i seg selv; går det ikke tydelig fram av koden hva som skjer, så refoktorer slik at du slipper å sitte der 2 år etterpå og være frustrert over å ikke skjønne hvordan du har tenkt.

 

Enkelte unødvendige kommentarer kan være nyttige om man bruker automatisk dokumentasjonsgenerering. RDoc på Ruby f.eks. - en sånn "unødvendig" kommentar kan da gjøre dokumentasjonen bedre.

[steingrim]

Det er situasjoner hvor en property trenger en liten beskrivelse(ikke ofte, men det skjer), og i java så har man ingen umiddelbar kobling mellom den private variablen og setter/getter.

 

Hvor skal man da dokumentere?

Men nå snakker du ikke lenger om en ordinær get/setter! Og da er det helt greit og kommentaren din vil overleve code-review av meg

[tomsi42]

Selvdokumenterende kode er jeg også sterk tilhenger av.

 

Men det hender at man skal kode rundt eksterne eller gamle ting. Og da må det litt dokumentasjon til. La oss ta et eksempel. Jeg holder på å lage et program som ripper CD'er og her henter jeg data i CDDB formatet (fra freedb). Der har vi tre attributter som bør dokumenteres for de som ikke er kjent med formatet: discid, category og genre. discid er ikke direkte innlysende, og hva er forskjellen mellom category og genre ...

 

Og slik er det innemellom ...

[tomsi42]

Men nå snakker du ikke lenger om en ordinær get/setter! Og da er det helt greit og kommentaren din vil overleve code-review av meg

Her skal man være kjapp for å følge med

[NevroMance]

Helt enig i at det er mange rare kode"standarder" ute og går, men i jobbsammenheng mener jeg det burde taes på bedriftens kappe. Det at det ikke er en veldeffinert kodestandard i bedriften er jo rett og slett livsfarlig. En person som skriver dårlig kode, som ofte kun han/hun skjønner vil skape store problemer når den drar.

 

Hvis det er definerte standarer i bedriften og arbeidstagere velger å ikke følge dette må bedriften igjen ta seg av det.

 

Det at noen muligens mener standarden i bedriften er på trynet er jo igjen noe helt annet, men det at to personer i samme bedrift har vidt forskjellig standard på koden sin kan være veldig skummelt.

 

Hvis det er ett problem på arbeidsplassen din, har du vurdert å ta det opp? Sette sammen en gruppe som setter opp en kodestandard som alle skal følge kan muligens være veien å gå, sammen med code reviews.

 

Jeg vil ikke kommentere noe om hva som burde regnes som best stil, da hver og en har sin egen mening om det, men det viktige er, i mine øyne, og faktisk lage en standard som alle i en bedrift/ett prosjekt skal følge.

[___]

Du glemte den tredje varianten:

 

function(args) {
... }

 

Da sparer man hele TO linjer

 

W