Hvilket bud bryter du oftest?

[torbjørn marø]

Egoløs Programmering er et konsept hvor personlige faktorer minimeres for å øke kvaliteten på det som produseres. Er interessert i å se hva dere på forumet mener om hvilke av disse dere bryter oftest, eller ikke tenker på i hverdagen.

[GeirGrusom]

Du mangler "Kommenter og dokumenter hva du gjør godt!" for den bommer jeg selv på, og sitter og biter meg i armen over at forgjengeren min var minst like ille som meg.

[torbjørn marø]

Du mangler "Kommenter og dokumenter hva du gjør godt!" for den bommer jeg selv på, og sitter og biter meg i armen over at forgjengeren min var minst like ille som meg.

Jeg kommenterer omtrent ALDRI koden min. Skiver lesbar kode i stedet. Kommentarer lyver - når du endrer koden så glemmer du å endre kommentarene, og da er det bare forvirrende og kan føre til feil. Selvdokumenterende kode rules!

Endret 3. mai 2011 av torbjørn marø

[GeirGrusom]

Det virker sikkert veldig selvsagt for deg hva koden din gjør, men prøv å sett deg inn i fullstendig udokumentert kode som noen andre har skrevet en gang. Det er egoløst å faktisk dokumentere det du skal gjøre før du engang gjør det. Andre skal kanskje bruke koden etter deg.

Endret 3. mai 2011 av GeirGrusom

[torbjørn marø]

Det virker sikkert veldig selvsagt for deg hva koden din gjør, men prøv å sett deg inn i fullstendig udokumentert kode som noen andre har skrevet en gang. Det er egoløst å faktisk dokumentere det du skal gjøre før du engang gjør det. Andre skal kanskje bruke koden etter deg.

Tror du misforstår. Jeg skriver SELVDOKUMENTERENDE kode. Jeg jobber på team med tre andre utviklere, og ingen av oss kommenterer. Det er egoistisk (og dumt) å skrive kode som ikke er enkel å forstå, helt enig, men kommentarer er ikke den eneste løsningen, og ikke den beste.

[GeirGrusom]

Selvdokumenterende kode finnes ikke. Har du en funksjon på kanskje 50-100 linjer fullstendig uten kommentarer, så sitter du med et par timers arbeid for å finne ut av hva den faktisk gjør, som kunne enkelt blitt oppsummert med et par linjer med ren tekst.

 

Derfor skriver man pre-condition og post-condition, pluss oppsummering og beskrivelse av alle argumenter og unntakstilstander. Når dette ikke forekommer er dette noe som alle nye må tyde utifra koden. Mildt sagt upraktisk.

[torbjørn marø]

Selvdokumenterende kode finnes ikke. Har du en funksjon på kanskje 50-100 linjer fullstendig uten kommentarer, så sitter du med et par timers arbeid for å finne ut av hva den faktisk gjør, som kunne enkelt blitt oppsummert med et par linjer med ren tekst.

 

Derfor skriver man pre-condition og post-condition, pluss oppsummering og beskrivelse av alle argumenter og unntakstilstander. Når dette ikke forekommer er dette noe som alle nye må tyde utifra koden. Mildt sagt upraktisk.

Har du en funksjon på kanskje 50-100 linjer så skriver du ikke selvdokumenterende kode - helt korrekt! Skriver en av koderne mine en metode på 20 linjer så spør jeg hva i all hverden han holder på med. Mine egne funskjoner er sjelden på mer enn et par linjer.

 

Mine funksjonsnavn, variabelnavn og klassenavn erstatter i praksis dine kommentarer. Anbefaler deg å ta en titt på Robert C. Martins Clean Code.

[NikkaYoichi]

Kommentere koden og å gi variabler fornuftige navn. Mine variabler blir gjerne hetende kari, per, gunnar og andre egennavn. Jeg har et personlig forhold til variablene mine, nemlig!

[MailMan13]

Kommentarer råtner desverre. Ofte når man kommer inn i en kodebase som er noen år gammel så stemmer ikke nødvendigvis kommentarene med det som koden gjør lenger, så man kan ikke stole på dem likevel.

 

Gode navn, korte metoder og unit-tester med riktige navn og høy nok oppløsning er viktigst. "The good spec is the opne that excecutes". Da har man enkle test-cases som viser hvordan koden brukes og man har litt sikkerhet for at det som står der er korrekt, (build-miljøet gir deg forhåpentligvis rødt lys hvis du gjør noe som bryter med "spesifikasjonen" (dvs. testene).)

 

Gode dokumenterende kommentarer på standard-format er fint det, men jeg har utviklet sunn skepsis mot å ta alt som står i den for god fisk.

 

God kode med tester > god riktig kommentar > ingen kommentar > råtten kommentar.

 

My 2c.

Endret 3. mai 2011 av MailMan13

[Balthier]

upsie :/

Endret 3. mai 2011 av Balthier842

[Matsemann]

Du mangler "Kommenter og dokumenter hva du gjør godt!" for den bommer jeg selv på, og sitter og biter meg i armen over at forgjengeren min var minst like ille som meg.

Jeg kommenterer omtrent ALDRI koden min. Skiver lesbar kode i stedet. Kommentarer lyver - når du endrer koden så glemmer du å endre kommentarene, og da er det bare forvirrende og kan føre til feil. Selvdokumenterende kode rules!

Når man koder for seg selv, eller et såpass lite team som du gjør, funker det nok til en stor grad, siden alle vet hva som foregår.

 

Dessuten, lesbar kode for deg er ikke lesbar for andre. Selv om du snakker om funksjoner på et par linjer. Jeg skrev denne linjen i spillet mitt for noen uker siden, med en liten kommentar om hva den gjør. Veldig unødvendig å skille den ut i en egen funksjon, for da må jeg igang med å sende over parametere.

blockcopy[j] = blockArray;

 

Kunne du tenkt deg at dokumentasjonen til språket du skriver ikke inneholdt noen kommentarer?

[GeirGrusom]

Sitter og jobber i et prosjekt med masse tråder, objekter, pipelines og whatnot med svært lite kommenterer. koden er i seg selv godt skrevet, men det er fortsatt veldig vanskelig å sette seg inn i kode som har et call-hierarki med 10 nøstede funksjoner.

 

Lange funksjoner går forsåvidt greit det, så lenge det er godt dokumentert hva som faktisk skjer. Som regel er det unødvendig at jeg må gå inn i detaljer på hva som skjer i kode andre har skrevet, men når det ikke er noe som helst dokumentasjon på hva som skjer, så er det det eneste jeg kan gjøre.

Endret 3. mai 2011 av GeirGrusom

[torbjørn marø]

Når man koder for seg selv, eller et såpass lite team som du gjør, funker det nok til en stor grad, siden alle vet hva som foregår.

 

Dessuten, lesbar kode for deg er ikke lesbar for andre. Selv om du snakker om funksjoner på et par linjer. Jeg skrev denne linjen i spillet mitt for noen uker siden, med en liten kommentar om hva den gjør. Veldig unødvendig å skille den ut i en egen funksjon, for da må jeg igang med å sende over parametere.

blockcopy[j] = blockArray;

 

Kunne du tenkt deg at dokumentasjonen til språket du skriver ikke inneholdt noen kommentarer?

Føler på meg at dette svaret blir litt langt

 

Det er riktig at det er et passelig lite team, og det er en fordel, men teamet har kodet i årevis på de samme prosjektene, og nesten daglig kommer vi over kode som ikke har sett dagens lys på lange tider. Av og til er den bra, av og til dårlig. Av og til er den dokumentert, av og til ikke.

 

Kommentarene jeg finner stemmer ofte ikke med virkeligheten, så jeg kan ikke stole på dem. Dessuten kommenterer de som regel selvfølgeligheter, som er enklere å få med seg ved å lese koden. Viktige ting som er vanskelig å forstå mangler som regel kommentarer.

 

Jeg sa ikke at jeg aldri kommenterer, selv om jeg brukte ALL CAPS, men nesten aldri. Av og til er det riktig. Men før jeg skriver en kommentar forsøker jeg altid å omforme koden i stedet for å få frem meningen på en bedre måte. Klarer jeg det så dropper jeg kommentaren.

 

Har jobbet som profesjonell utvikler i 12 år, på mange ulike team og i veldig forskjellige prosjekter. Kodekommentarer har nesten aldri gitt meg noe fornuftig, og er bare irriterende (og i verste fall farlig) når de er tvetydige eller direkte feil.

 

Hvis jeg kan velge mellom rotete kode med kommentarer, og ren og pen kode uten kommentarer, så er det ikke noen tvil for meg hva jeg velger. Ren og pen kode med kommentarer der det virkelig trengs er det beste.

 

Kode har et par fordeler fremfor vanlig engelsk/norsk - det har en fast struktur, og det er ikke tvetydig. Strukturen gjør at det er enklere for oss å scanne med blikket for å parse ut meningen. Det sier seg selv hvorfor manglende tvetydighet er lurt. Koden er derfor et mye bedre verktøy for å få frem meningen klart å presist enn det vanlig engelsk/norsk er - når det gjøres riktig og med omtanke vel og merke.

 

Hukommelsen min er elendig, og hvis jeg har kodet noe med dårlig struktur og ser på det bare en uke senere så sliter jeg med å skjønne hva som skjer. Men er strukturen bra så trenger jeg ikke kommentarer. Selvdokumenterende kode virker, jeg lover!

 

Programmeringsspråk er laget for å være lesbare for mennesker. Som utvikler (på mitt team i alle fall) er din oppgave å skrive kode som er lett å lese for mennesker. Datamaskinen kommer i andre rekke. Vi koder jo tross alt ikke i Assembly heller

 

Og ja, ok, jeg er glad for at programmeringsspråkene jeg bruker er godt dokumentert. Men som regel holder det å se signaturen til en funksjon, og så vet jeg hva den gjør. Jeg behøver ALDRI se på innholdet i en funksjon for å finne ut hvordan den virker. Gjør metodene dine noe som ikke er beskrevet i navnet bør du tenke deg om. Utviklere som bruker koden din kan fort få seg noen ubehagelige overraskelser. Man leser dokumentasjon når noe ikke fungerer som antatt. Hvis ting fungerer som antatt så slipper man.

[torbjørn marø]

Sitter og jobber i et prosjekt med masse tråder, objekter, pipelines og whatnot med svært lite kommenterer. koden er i seg selv godt skrevet, men det er fortsatt veldig vanskelig å sette seg inn i kode som har et call-hierarki med 10 nøstede funksjoner.

Det høres ut som deler av vår kode - masse tråder, og vanskelig å lese hva som skjer fordi ting er spredt veldig. Det du trenger da er dokumentasjon med et høyere nivå som beskriver hvordan objektene jobber sammen. Et word-dokument kanskje, noen diagrammer. Det er ikke det jeg snakker om når vi diskuterer kommentarer i kode - høy-nivå-dokumentasjon er ofte viktig, selv om den ofte også er vanskelig å vedlikeholde etterhvert som kodebasen endrer seg.

[GeirGrusom]

Sitter og jobber i et prosjekt med masse tråder, objekter, pipelines og whatnot med svært lite kommenterer. koden er i seg selv godt skrevet, men det er fortsatt veldig vanskelig å sette seg inn i kode som har et call-hierarki med 10 nøstede funksjoner.

Det høres ut som deler av vår kode - masse tråder, og vanskelig å lese hva som skjer fordi ting er spredt veldig. Det du trenger da er dokumentasjon med et høyere nivå som beskriver hvordan objektene jobber sammen. Et word-dokument kanskje, noen diagrammer. Det er ikke det jeg snakker om når vi diskuterer kommentarer i kode - høy-nivå-dokumentasjon er ofte viktig, selv om den ofte også er vanskelig å vedlikeholde etterhvert som kodebasen endrer seg.

 

Ikke bare det. hver funksjon må ha en beskrivelse av hva den gjør. Hver løkke burde også ha det osv.

 

//Increment a
a++;

Er dog unødvendig.

 

Men jeg vil ikke se funksjoner som ser slik ut uten kommentarer:

 

public void CalibrateClockTimerProcess()

 

Jeg var også borti funksjoner som redigerte globale objekter, selv om definisjonen på funksjonen ikke hintet mot at det var faktisk noe den gjorde. Og kommentarer manglet fullstendig som nevnte dette med et ord. Jeg fant ut av det når jeg så i koden, men det burde strengt tatt vært unødvendig.

Det som også irriterte meg med den, var at den brukte en rekke variabler i strukturer, som hadde navnenene spacing, og offset i seg. Det sto ingenting om hva dette betydde, så jeg gjettet hva de ble brukt til, og jeg gjettet selvsagt feil. Hva de ble brukt til fant jeg ikke ut før jeg testet koden praktisk og endret verdiene.

 

Hadde dette faktisk vært dokumentert med noe annet enn C kode, så hadde det vært fullstendig unødvendig.

[MailMan13]

Hadde dette faktisk vært dokumentert med noe annet enn C kode, så hadde det vært fullstendig unødvendig.

Ville du ikke heller da at den opprinnelige utvikleren hadde laget et bedre design på den slik at den gjør bare en ting, og sjekket det inn med en unit-test som spesifiserer, demonstrerer og verifiserer hva den gjør, slik at du faktisk deterministisk kan si "ja, slik er det"? Hvis problemet er at en utvikler har laget en funksjon gjør mer enn navnet tilsier så er det jo funksjonens navn som er problemet?

 

Kode som dokumentasjon kan kanskje være tyngre å lese enn kommentarer i en del tilfeller, i når man kommer dit at produksjonskode + unit-test ikke er tilstrekkelig, så er utfyllende kommentar nødvendig og riktig verktøy. Ikke før.

 

Problemet du beskriver kan patches med kommentarer som dokumentasjon, men det høres ikke ut som mangel på kommentarer er det grunnleggende problemet der...

 

Ikke bare det. hver funksjon må ha en beskrivelse av hva den gjør. Hver løkke burde også ha det osv.

 

Her holder jeg en knapp på:

 // Does some stuff
for(...) 
{
...
}

som kan gjøres redudant med

for(...) 
{
DoSomeStuff();
}

Som i de fleste tilfeller er nok, hvis ikke så har man selvfølgelig også lett tilgjengelig:

@Test
public void Does_some_description_of_stuff() 
{
   result = _subject.DoSomeStuff();
   Assert.That(result, Is.Correct(result));
}

[torbjørn marø]

Veldig enig i det MailMan13 sier.

 

Husk også at de kommentarene en ofte får bruk for å lese er ting som beskriver intensjon; hvorfor gjør denne koden det den gjør. Som regel kommenterer man i stedet hva koden gjør, noe man i de fleste tilfeller like lett ser ut fra koden.

[Gjest Slettet+9871234]

Du mangler "Kommenter og dokumenter hva du gjør godt!" for den bommer jeg selv på, og sitter og biter meg i armen over at forgjengeren min var minst like ille som meg.

Jeg kjenner kun et språk der koden er tilnærmet selvdokumenterende: Simula http://www.kjellbleivik.com/Books/#simula .

 

Som et minimum:

 

//Dette er gjennomsiktlig for meg, men kanskje ikke for deg som leser det.

 

Jeg har et eget avsnitt om dette http://www.oopschool.com/#optimizestructure på min side der dokumentasjon er en del av emnet. Dvs avsnitt i betydningen lenker til relevant stoff skrevet for noen år tilbake.

 

Der var visst ikke mye om dokumentasjon der: Denne http://www.phpdoc.org/ er ihvertfall viktig for php programmerere. I tillegg kan docblock's brukes til å generere høynivå dokumentasjon.

 

Dockblocks har formen:

 

/**
* Login a user
*
* Logs in a user, applying their credentials against those found in
* the database.
*
* @param string $user Username
* @param string $password User's password
* @return boolean
* @throws Exception on database error
*/

 

Kommentarer råtner desverre. Ofte når man kommer inn i en kodebase som er noen år gammel så stemmer ikke nødvendigvis kommentarene med det som koden gjør lenger, så man kan ikke stole på dem likevel.

Ovenfor nevnte docblocks løser delvis det når det gjelder dokumentasjon utenfor koden, og da må man tenke på å oppdatere docblocks samtidig som koden endres.

 

Programmeringsspråk er laget for å være lesbare for mennesker. Som utvikler (på mitt team i alle fall) er din oppgave å skrive kode som er lett å lese for mennesker. Datamaskinen kommer i andre rekke. Vi koder jo tross alt ikke i Assembly heller

Jo noen gjør fortsatt det og der setter Peter Norton en standard på dokumentasjon i assembly kode.

 

Det du trenger da er dokumentasjon med et høyere nivå som beskriver hvordan objektene jobber sammen. Et word-dokument kanskje, noen diagrammer. Det er ikke det jeg snakker om når vi diskuterer kommentarer i kode - høy-nivå-dokumentasjon er ofte viktig, selv om den ofte også er vanskelig å vedlikeholde etterhvert som kodebasen endrer seg.

I php tar phpdocumentor seg av det, men da må koden være dokumentert på ordentlig måte.

Endret 3. mai 2011 av Slettet+9871234

[MailMan13]

Ovenfor nevnte docblocks løser delvis det når det gjelder dokumentasjon utenfor koden, og da må man tenke på å oppdatere docblocks samtidig som koden endres.

Den løser alt utenom det som var problemet da

 

Trenger man å lage formell API-dokumentasjon er verktøy som JavaDoc/NDoc/Doxygen, og sikkert docblocks også, definitivt fine dem, ingen tvil om det. Vi bruker NDoc flittig når vi lager ting som skal eksponeres eksternt og må dokumenteres.

 

Men dem rører desverre ikke ved årsaken til problemet. Det gjør derimot et godt test-rammeverk

 

Jeg heller heller litt andre veien, at dem aksellerer problemet siden ligger på en måte et insentiv på brukeren om å kommentere ting som ikke trenger kommentarer, og øke mengden "dokumentasjon" som potensielt råtner og blir misvisende.

 

/**
* Login a user
*
* Logs in a user, applying their credentials against those found in
* the database.
*
* @param string $user Username
* @param string $password User's password
* @return boolean
* @throws Exception on database error
*/

Er et godt eksemplel på dårlig bruk av kommentarer, fremtvunget av feil rammeverk-bruk. Den sier ingenting som signaturen til metoden ikke også kan kommunisere. Den er 100% redudant og den har lagt til 6-7 linjer med tekst som må vedlikeholdes ved siden av koden, for ikke å bli feil i tillegg til unødvendig. For meg blir dette "dokumentasjon", og ikke dokumentasjon.

 

Vel, den sier "Applying their credentials against those found in the database.", som sannsynligvis er feil siden et godt design vil delegere den biten, slik at det blir gjenbrukbart og testbart uten avhengiget til noe database-API

 

Nå er jeg klar over at dette var ment som et eksempel på format, og ikke god praksis. Men i kodebaser som aktivt bruker dokumentasjonsverktøy av JavaDoc/NDoc/Doxygen-typen er det min erfaring at mesteparten av kommentarene faktisk ser omtrent slik ut.

 

Min versjon:

class Authenticator {
   public Rights LoginUser(string username, string password) {...}
}

 

Sier akkurat det samme, men det skal mer til å få den lyve siden det er kode som faktisk kjører.

 

Så, hvis man vil vite mer om hva som foregår kan man enten se i selve koden, eller se i testene som ligger ved siden av, som f.eks inneholder bla.annet:

@TestFixture
class Authenticator_Login_Tests {
   @Test
   public void Authenticates_credentials() {...}

   @Test
   public void Logs_attempt_in_audit_log() {...}

   @Test
   public void Returns_rights_on_success() {...}

}

 

Mener ikke å si "all comments are evil", for all del. Men kommentarer for kommentarens skyld, nei takk. Den må fortelle noe som ikke allerede kommuniseres av navn og argumenter. Gjør den ikke det taper man ingenting på å la være.

Endret 3. mai 2011 av MailMan13

[Gjest Slettet+9871234]

Nå er jeg klar over at dette var ment som et eksempel på format, og ikke god praksis. i

Ja det stemmer og det var klippet fra det første kode eksemplet jeg kunne finne. Jeg har ikke brukt det i mine applikasjoner så langt.

 

Men kommentarer for kommentarens skyld, nei takk.

Enig i det.