mboost-dp1
5 Signs You Should Hire a Programmer on the Spot
Ved ikke rigtigt om jeg er enig i tegnene:
1. Det er fint nok at kunne flere løsninger til et givent problem. Der er faktisk et krav at man kan skele imellem forskellige forkus/tilgang til et givent stykke kode. Men man skal stadigvæk kun implementere én og så skal man forøvrigt vælge den rigtige og kunne argumentere for den.
2. Fuld dokumentation til noget test-kode? Bah! Jeg tror at vi tager noget selvdokumenterende i stedet. Ham her lyder som en autist.
3. Han forbedrer testene? Fint, fint, men har han overvejet konsekvenserne af at rette løs i kode, der allerede er releaset?
4. Han har svært ved at slippe koden? Refaktoring er et must hvis man skipper den klassiske dokumentation. Men jeg vil foretrække hvis det er et enten/eller. Og "svært ved at slippe koden" lyder bare overhovedet ikke attraktivt.
5. Lyder som et rigtigt godt argument. Men det er vist ikke kun forbeholdt programmøre.
1. Det er fint nok at kunne flere løsninger til et givent problem. Der er faktisk et krav at man kan skele imellem forskellige forkus/tilgang til et givent stykke kode. Men man skal stadigvæk kun implementere én og så skal man forøvrigt vælge den rigtige og kunne argumentere for den.
2. Fuld dokumentation til noget test-kode? Bah! Jeg tror at vi tager noget selvdokumenterende i stedet. Ham her lyder som en autist.
3. Han forbedrer testene? Fint, fint, men har han overvejet konsekvenserne af at rette løs i kode, der allerede er releaset?
4. Han har svært ved at slippe koden? Refaktoring er et must hvis man skipper den klassiske dokumentation. Men jeg vil foretrække hvis det er et enten/eller. Og "svært ved at slippe koden" lyder bare overhovedet ikke attraktivt.
5. Lyder som et rigtigt godt argument. Men det er vist ikke kun forbeholdt programmøre.
illishar (2) skrev:1. [...]Men man skal stadigvæk kun implementere én
Til dagligt, ja. Men til en jobsamtale er det fint at vise sig frem.
illishar (2) skrev:2. Fuld dokumentation til noget test-kode? Bah
Helt enig. Hvis der er behov for at dokumentere kode, er det typisk et tegn på at man burde refaktorere. Men mere generelt kan jeg godt lide når folk betragter dokumentation, unit tests og refaktorering som en del af opgaven, i stedet for at stoppe når det virker.
Jeg ved ikke helt hvad "full documentation" dækker over ved kode, men det lyder skræmmende.
Ellers enig.
Andre steder undrer debatører sig over at ansøgeren bliver vurderet ud fra ting som ikke fremgår af opgaven. Det synes jeg er indlysende.
Man bliver vel heller ikke bedt om at tage pænt tøj på til jobsamtalen, men man bliver skam vurderet på det. Hvis man bliver bedt om at få et stykke kode til at virke, så er det typisk implicit at koden skal være pæn osv, uanset om det er jobsamtale eller job.
Testen handler ikke kun om at løse opgaven. Den handler også om hvordan man løser den, og hvordan man arbejder.
Man bliver vel heller ikke bedt om at tage pænt tøj på til jobsamtalen, men man bliver skam vurderet på det. Hvis man bliver bedt om at få et stykke kode til at virke, så er det typisk implicit at koden skal være pæn osv, uanset om det er jobsamtale eller job.
Testen handler ikke kun om at løse opgaven. Den handler også om hvordan man løser den, og hvordan man arbejder.
illishar (2) skrev:1. Det er fint nok at kunne flere løsninger til et givent problem. Der er faktisk et krav at man kan skele imellem forskellige forkus/tilgang til et givent stykke kode. Men man skal stadigvæk kun implementere én og så skal man forøvrigt vælge den rigtige og kunne argumentere for den.
myplacedk (3) skrev:Til dagligt, ja. Men til en jobsamtale er det fint at vise sig frem.
Nej hvor det plasker.
Jeg vil absolut betragte det som best practice at man ved problemer hvor det ikke er åbenlyst hvilken løsning der er bedst prøver at implementere flere for at se hvordan de ender op.
illishar (2) skrev:2. Fuld dokumentation til noget test-kode? Bah! Jeg tror at vi tager noget selvdokumenterende i stedet. Ham her lyder som en autist.
myplacedk (3) skrev:Helt enig. Hvis der er behov for at dokumentere kode, er det typisk et tegn på at man burde refaktorere.
Selvdokumenterende kode uden behov for dokumentation??
Nogen der vil købe en bro?
myplacedk (3) skrev:Men mere generelt kan jeg godt lide når folk betragter dokumentation, unit tests og refaktorering som en del af opgaven, i stedet for at stoppe når det virker.
Netop. Kode uden dokumentation og unit test er simpelthen ikke færdigt.
myplacedk (6) skrev:Jeg håber ikke han sidder og laver API dokumention, hvis det ikke er et API han laver. Men det fremgår da godt nok ikke af artiklen.
Der oplyses at der skrives unit tests. Det betyder vel at der er et API.
arne_v (8) skrev:Selvdokumenterende kode uden behov for dokumentation??
Ikke HELT uden dokumentation. :)
Men i hvert fald i det kode JEG ser, er de fleste kommentarer et alternativ til at refaktorere.
arne_v (8) skrev:Der oplyses at der skrives unit tests. Det betyder vel at der er et API.
Måske snakker vi lidt forbi hinanden. Man kan sagtens lave unit-tests på noget som ikke skal udstilles uden for sammenhæng.
myplacedk (10) skrev:Måske snakker vi lidt forbi hinanden. Man kan sagtens lave unit-tests på noget som ikke skal udstilles uden for sammenhæng.
Hvad er "noget som ikke skal udstilles uden for sammenhæng"?
Hvis metoderne er public, så er det vel overvejende sandsynligt at der i løbet af de næste 10-20 år er andre end udvikleren selv som skal enten skrive kode der kalder dem eller læse kode der kalder dem og som dermed vil have nytte af noget Java Doc?
arne_v (11) skrev:Hvad er "noget som ikke skal udstilles uden for sammenhæng"?
For eksempel at hvis du har noget med det at gøre, så har du allerede koden i dit IDE. Hvis du er i tvivl om hvad en metode gør, kan du trykke én tast for at få Javadoc, eller en anden tast for at få kode frem. Hvis den kode er nogenlunde lige så nem at læse som dokumentation, ser jeg ingen grund til at dokumentere.
Og nogle gange er dokumentation bare latterligt og i vejen når man prøver at overskue koden:
/** Sets the name
* @param name
*/
public void setName(String name) {
this.name = name;
}
Noget kode er bare dokumenteret tilstrækkeligt med god struktur og navngivning. Og når det ikke er nok, er det nogle gange lettere at læse indholdet af metoden, end at skrive dokumentation til det hele i håbet om at nogen engang læser det.
Især i betragtning af at dokumentation af kode ofte er misvisende. Måske har man lavet en kodefejl, som folk ikke opdager fordi de læser i kommentaren hvad koden gør. Måske er koden ændret uden at kommentaren er ændret.
arne_v (8) skrev:
Selvdokumenterende kode uden behov for dokumentation??
Nogen der vil købe en bro?
Hvis din dokumentations-løse bro koster 100k og din dokumenterede bro koster 5M, så vil jeg ihvertfald gerne have valget. Især hvis broen bliver bygget af interne erfarende brobyggere, udelukket til brug for virksomhedens egen transport.
Derudover er selvdokumenterende kode + inline dokumentation heller ikke det samme samme som "ingen dokumentation". Det betyder blot at man finde skal finde dokumentationen i forbindelse med eller i den pågældende kode.
Og det er naturligvis heller ikke alt der skal "inline dokumenteres". myplacedk giver et godt eksempel på dokumentation der er direkte skadeligt for koden. (Hvis det er lettere at læse og forstå, uden den pågældende dokumentation, så er den skadelig.)
Grundet risici for "out-of-sync" så er klassisk (ekstern) dokumentation ofte lidt af en epic fail, som vist mest finder sin berettigelse i de store klassiske kontraktdrevene SPU-projekter. (Og her taler jeg ikke om salgsdokumentation eller brugermanualer e.l.)
Dokumentering ala Javadoc lider dog også af "out-of-sync" og risikerer derfor at skabe unødvendige fejl-situationer over lang sigt. Et velformuleret funktionsnavn kan derfor være at foretrække, da dette giver den bedste integritet. Det kommer an på ambitionsniveau og budget.
myplacedk (13) skrev:For eksempel at hvis du har noget med det at gøre, så har du allerede koden i dit IDE. Hvis du er i tvivl om hvad en metode gør, kan du trykke én tast for at få Javadoc, eller en anden tast for at få kode frem. Hvis den kode er nogenlunde lige så nem at læse som dokumentation, ser jeg ingen grund til at dokumentere.
myplacedk (13) skrev:Noget kode er bare dokumenteret tilstrækkeligt med god struktur og navngivning. Og når det ikke er nok, er det nogle gange lettere at læse indholdet af metoden, end at skrive dokumentation til det hele i håbet om at nogen engang læser det.
Jeg er ikke specielt overbevist.
Af to grunde.
For det første bør en rimelig opdeling i projekter sikre at de fleste public metoder faktisk bruges af andre projekter, hvor projekts source kode ikke nødvendigvis er til rådighed. Package visibility (Java) eller internal protected visibility (.NET) bør bruges til alt det interne.
For det andet så er det rigtigt at mange metoder er så trivielle at man kan læse kode lige så hurtig som dokumentationen, men der er også metoder hvor det ikke er tilfældet. Og det er ikke særligt praktisk at slå op i koden og hvis det er en kompleks metode så slå op i dokumentationen bagefter.
myplacedk (13) skrev:Især i betragtning af at dokumentation af kode ofte er misvisende. Måske har man lavet en kodefejl, som folk ikke opdager fordi de læser i kommentaren hvad koden gør. Måske er koden ændret uden at kommentaren er ændret.
Det sker. Det sker meget tit.
Men jeg er absolut ikke glad for princippet om at man kan undlade at skrive dokumentation fordi den kan være forkert. Overførsel af dette principe på andre problem stillinger kunne bruges mod de fleste best practices indenfor software udvikling.
arne_v (7) skrev:Jeg vil absolut betragte det som best practice at man ved problemer hvor det ikke er åbenlyst hvilken løsning der er bedst prøver at implementere flere for at se hvordan de ender op
Personligt vil jeg stadigvæk forestrække hvis udvikleren har et fokus i forbindelse med koden. Selvom man blindt implementerer forskellige løsninger, hvis eneste umiddelbare egneskab er at de er forskellige, så skal man stadigvæk kunne konstatere hvilken der er den bedste. Hvis man blindt implmenterer 2 løsninger og derefter laver profiling for at finde den med bedst performance, så får man bestemt et stort plus, for at være en god student af Knuth. Men det lyder ikke som om at den pågældende situation var med henblik på hverken profiling eller performance. Og man bør også helst have en lidt bedre målsætning inden man begynder, end at "den her løsning er forskellig fra den anden".
Relevante forskellige mål kunne være ting som:
- Performance
- Memory
- Code size
- Code readablity
- Maintainance/Extensibility
- Robustness
- Correctness
- Etc.
I en job-test-situation vil jeg derfor hellere have en kandidat hvis éne rekursive løsning er lavet med henbilk på "readability" til gengæld for en pris på "voldtægt af stack'en" (whatever), i forhold til en tilsvarende iterativ løsning. At en person er i stand til at implementere en løsning på to forskellige måder er selvfølgelig en god ting. Men vi skal helst være kommet lidt længere det.
Jeg plejer at argumentere for dokumentation sådan her: Hvis en programmør ikke kan dokumentere en metode, så er denne metode for kompleks og skal splittes op i flere mindre metoder, som så kan dokumenteres.
Altså, hvis man ikke kan forklare hvad en metode gør med et par linjers tekst, har man et problem.
Altså, hvis man ikke kan forklare hvad en metode gør med et par linjers tekst, har man et problem.
illishar (14) skrev:Hvis din dokumentations-løse bro koster 100k og din dokumenterede bro koster 5M, så vil jeg ihvertfald gerne have valget.
Den prisforskel er ikke realistisk.
illishar (14) skrev:Især hvis broen bliver bygget af interne erfarende brobyggere, udelukket til brug for virksomhedens egen transport.
Dette argument bruges ofte.
Men erfaring viser at kode ofte bliver brugt i mange flere år end oprindeligt tiltænkt og at udviklere skifter jobs betydeligt hurtigere end koden erstattes af anden kode.
Så selvom man idag har et team som sagtens kan klare sig uden dokumentation fordi de via erfaring kender koden forfra og baglæns, så kan der om 10 år godt sidde nogle maintenance programmører som slet ikke har den viden.
Hvis firmaet evt. skulle beslutte sig for at outsource maintenance engang i fremtiden, så kan det koste meget dyrt med manglende dokumentation.
illishar (14) skrev:Grundet risici for "out-of-sync" så er klassisk (ekstern) dokumentation ofte lidt af en epic fail,
Ekstern dokumentation skal helst forholde sig til design ideer og principper og ikke gå i kode detaljer, fordi sandsynligheden for at den ikke bliver opdateret ved kode ændringer er stor.
illishar (14) skrev:Dokumentering ala Javadoc lider dog også af "out-of-sync" og risikerer derfor at skabe unødvendige fejl-situationer over lang sigt.
Java Doc giver faktisk warnings ved generering hvis signaturen i Java Doc comment og signaturen i Java ikke matcher.
Den kan naturligvis ikke fange ændringer i hvad metode gør.
illishar (14) skrev:Et velformuleret funktionsnavn kan derfor være at foretrække, da dette giver den bedste integritet.
Jeg tror ikke at nogen argumenterer imod gode navne.
Men jeg vil argumentere imod at gode navne skulle overflødiggøre dokumentation.
illishar (14) skrev:Det kommer an på ambitionsniveau og budget.
Hvad der er muligt afhænger af hvor presset projektet er.
Men det at skippe dokumentation for at få projektet færdigt on budget kan godt koste mere i det lange løb.
arne_v (16) skrev:Men jeg er absolut ikke glad for princippet om at man kan undlade at skrive dokumentation fordi den kan være forkert
Man skal heller ikke undlade at skrive dokumentation. Man skal blot flytte den så tæt på den relevante funktionalitet som muligt. Jo tættere, jo bedre integritet. Et selvbeskrivende funktionsnavn har større sandsynlighed for at være korrekt, end den ovenstående Javadoc. Derudover er det ofte ikke nødvendigvis realistisk at forsyne eller forudse den mængde dokumentation som den anden part har brug. Eks. hvis man sammenligner MSDN dokumentationen til .NET, så er funktionsnavnene ofte lige så informative som dokumentationen. Host. Derfor har man tit brug for at reflekte en given funktion for at finde ud af hvad der egentlig sker. Måske siger det mere om Microsoft? (Og .NET-kode er derudover ret hurtig at læse igennem.) Men jeg synes nu at det samme også er tilfældet for så mange andre frameworks. Derfor kan man givetvis spare på dokumentationen og så i stedet gøre koden (den rigtige dokumentation) lettere tilgængelig?
arne_v (15) skrev:For det første bør en rimelig opdeling i projekter sikre at de fleste public metoder faktisk bruges af andre projekter, hvor projekts source kode ikke nødvendigvis er til rådighed. Package visibility (Java) eller internal protected visibility (.NET) bør bruges til alt det interne.
Jeg kan ikke se hvad public/private har med sagen at gøre. Hvis en metode ikke er relevant at forstå når man ikke arbejder med det projekt metoden er i, så er jeg ligeglad med om det er en public metode som man uden indsigt i arkitekturen kan tro kan kaldes udefra.
arne_v (15) skrev:For det andet så er det rigtigt at mange metoder er så trivielle at man kan læse kode lige så hurtig som dokumentationen, men der er også metoder hvor det ikke er tilfældet.
Jeg har skam heller ikke sagt at metoder ikke må dokumenteres. Jeg siger blot at behov for dokumentation ofte dækkes bedre med refactoring.
arne_v (15) skrev:Og det er ikke særligt praktisk at slå op i koden og hvis det er en kompleks metode så slå op i dokumentationen bagefter.
Det kommer vel an på setup'et. Hvis det er samlet er der ikke den store forskel.
Hos os trykker man F3 for at komme til kilden. I den fil man ryger hen til kommer kilden så lige efter cursoren, og eventuel dokumentation er lige før.
arne_v (16) skrev:Men jeg er absolut ikke glad for princippet om at man kan undlade at skrive dokumentation fordi den kan være forkert.
Hvis dokumentation ikke gavner men kan skade, så synes jeg altså absolut at man skal lade være med at skrive den.
Hvis dokumentation gavner mere end risikoen for at skade, skal man selvfølgelig skrive den. (Medmindre det er en bedre ide at refactorere i stedet.)
arne_v (19) skrev:Så selvom man idag har et team som sagtens kan klare sig uden dokumentation fordi de via erfaring kender koden forfra og baglæns,
Det er skam også et rigtigt dårligt argument. Koden skal ikke være nem at forstå fordi man kender den, den skal være nem at forstå fordi den er velskrevet.
Windcape (18) skrev:Hvis en programmør ikke kan dokumentere en metode, så er denne metode for kompleks og skal splittes op i flere mindre metoder, som så kan dokumenteres.
Og når man så har splittet dem op, så kan man passende give dem nogle store beskrivende navne, som siger dem samme som det man ville have skrevet i javadoc'en. (Så er der ikke brug for javadoc. Og så er integriteten forbedret. Og der hvor man kalder funktionerne, vil nu have mindre brug for kommentering.)
arne_v (20) skrev:Men jeg vil argumentere imod at gode navne skulle overflødiggøre dokumentation.
Det er der heller ikke nogen der siger. Men det overflødiggør MEGET dokumentation. Og hvis dokumentationen er overflødig skal man naturligvis ikke skrive den.
arne_v (20) skrev:Men det at skippe dokumentation for at få projektet færdigt on budget kan godt koste mere i det lange løb.
Helt enig. Skal man spare er fx. dokumentation og refactoring MEGET kortsigtet.
Dokumentation er til non-functional forklaringer.illishar (25) skrev:Og når man så har splittet dem op, så kan man passende give dem nogle store beskrivende navne, som siger dem samme som det man ville have skrevet i javadoc'en.
Eksempler kunne være hvilken algoritme der bruges, hvad Big O værdien er, hvilken webservice der bliver queuet for data, hvilket opløsning man henter data'en i (for f.eks. billeder og/eller video), osv.
Er det nu jeg skal foreslå, at man hvis man kombinerer "selvdokumentering" med design patterns, så kan man også i mange tilfælde undervære noget af det højere-liggende dokumentation?
Uh!
Den er nu ikke altid helt så god synes jeg. Det kræver lidt at alle personer indforstået med de samme termer.
Uh!
Den er nu ikke altid helt så god synes jeg. Det kræver lidt at alle personer indforstået med de samme termer.
arne_v (8) skrev:Kode uden dokumentation og unit test er simpelthen ikke færdigt.
... Nu er det ikke fordi jeg mener at man ikke skal lave unit tests. Men der findes også andre måde at fejlrette kode på. Rent økonomisk så skulle ting som "strukturerede reviews" statistisk set, være markant mere effektive end unit tests. (ref: Steve McConnell).
illishar (30) skrev:Nu er det ikke fordi jeg mener at man ikke skal lave unit tests. Men der findes også andre måde at fejlrette kode på. Rent økonomisk så skulle ting som "strukturerede reviews" statistisk set, være markant mere effektive end unit tests. (ref: Steve McConnell).
Og det tror jeg på. Ihvertfald i den fortolkning at brug af formal reviews sænker antallet af fejl i applikationen når den tages i brug mere end brug af unit tests gør.
Fordi unit tests fanger mest de simpel fejl, som alligevel ville være blevet fundet i test. Mens formal reviews kan fange de grimme fejl som kan snige sig gennem en test.
Men der er 2 aspekter af unit tests man lige skal husk på:
1) Det er billigere at finde fejl i unit tests end at lade QA finde dem, så selvom fejlene alligevel ville være fundet kan det være en god investering.
2) Den store fordel ved unit tests er slet ikke i udvikling men i maintenance. Det koster formentligt ikke mere tid at lave et formal review end det gør at skrive en unit test suite. Men det er meget meget hurtigere at genbruge unit test suiten efter nogle rettelser end det er at lave et formal review af rettelserne. Den helt store fordel ved unit tests er at man kan køre dem senere når man roder lidt ved koden til lynhurtigt at verficere om man har brudt nogle kontrakter.
Så jeg vil ikke lade formal reviews erstatte unit tests.
Meget gerne begge dele.
Hvis jeg skulle prioritere og kun vælge en af dem så tror jeg at ville vælge unit tests p.g.a. nytten i de 10-20 år hvor koden skal maintaines selvom de nok giver mindre bang for the buck i det originale projekt.
myplacedk (22) skrev:
Jeg kan ikke se hvad public/private har med sagen at gøre. Hvis en metode ikke er relevant at forstå når man ikke arbejder med det projekt metoden er i, så er jeg ligeglad med om det er en public metode som man uden indsigt i arkitekturen kan tro kan kaldes udefra.
public metode som kræver indsigt i arkitekturen ikke at kalde udenfor projekt => total fail i software dsign
public metode som har en fed blinkende note i dokumentationen om at den ikke kan kaldes udenfor projekt => workaround
non public metode => the way
myplacedk (13) skrev:navngivning.
illishar (21) skrev:Et selvbeskrivende funktionsnavn
illishar (25) skrev:så kan man passende give dem nogle store beskrivende navne, som siger dem samme som det man ville have skrevet i javadoc'en.
Navngivning af metoder kan ikke løse et dokumentations behov.
Af 2 årsager.
For non-trivielle metoder vil navnet blive for langt ved at putte informationen i navnet.
Det duer ikke med OOP hvor et metodenavn tit vil være givet af et interface eller en virtuel/abstract metode som man overrider.
myplacedk (22) skrev:
Det kommer vel an på setup'et. Hvis det er samlet er der ikke den store forskel.
Hos os trykker man F3 for at komme til kilden. I den fil man ryger hen til kommer kilden så lige efter cursoren, og eventuel dokumentation er lige før.
Der bør stadigvæk være hurtigere altid at scrolle op og se doc fremfor at scrolle ned og se koden og hvis den så er non-triviel scrolle op igen og læse doc.
Men derudover er det rimeligt standard idag (Eclipse og VS) at se docs ved mouseover. Og det virker også med kode hvor man kun har docs og ikke source installeret.
illishar (2) skrev:Ved ikke rigtigt om jeg er enig i tegnene:
1. Det er fint nok at kunne flere løsninger til et givent problem. Der er faktisk et krav at man kan skele imellem forskellige forkus/tilgang til et givent stykke kode. Men man skal stadigvæk kun implementere én og så skal man forøvrigt vælge den rigtige og kunne argumentere for den.
Ja, men han skal jo ikke selv vælge den rigtige løsning, for så er han netop en dårlig programmør. Her formodes det jo at han ikke er ansat i virksomheden, så han skal helst stille muligheder til rådighed for at sikre sig at han kan ramme kundens behov. Og derefter kan de sammen finde den rigtige løsning.
illishar (2) skrev:2. Fuld dokumentation til noget test-kode? Bah! Jeg tror at vi tager noget selvdokumenterende i stedet. Ham her lyder som en autist.
Det lyder måske voldsomt, men jeg vil også se det som et utroligt godt tegn at den slags kommer naturligt. For uden dokumentation, og helst gerne en som bliver skrevet løbende, så bliver den hurtigt glemt, og så får man ikke de vigtige detaljer med omkring formålet af de forskellige dele af koden.
Jeg gør det godt nok ikke selv, men jeg er så også langt fra professionel programmør / udvikler endnu.
illishar (2) skrev:3. Han forbedrer testene? Fint, fint, men har han overvejet konsekvenserne af at rette løs i kode, der allerede er releaset?
Som jeg har forstået det, så er den jo netop ikke released. Og hvis den er, kan der sagtens køre et test miljø samtidigt.
illishar (2) skrev:4. Han har svært ved at slippe koden? Refaktoring er et must hvis man skipper den klassiske dokumentation. Men jeg vil foretrække hvis det er et enten/eller. Og "svært ved at slippe koden" lyder bare overhovedet ikke attraktivt.
Har du nogen sinde oplevet der er blevet programmeret noget, som ikke skulle rettes til løbende, efterfølgende? Finpudsning af kode vil jeg mene er utrolig vigtigt. Så dumt at efterlade børnefejlene i et projekt og bare lade det hele stå til. Det kan altid gøres 10% bedre, men skal selvfølgelig også kunne overholde en deadline hvis der er en. Så må man derefter aftale hvordan kontrakten skal fortsætte og om der skal laves opdatering, eller gives yderligere support på koden efterfølgende.
illishar (2) skrev:5. Lyder som et rigtigt godt argument. Men det er vist ikke kun forbeholdt programmøre.
Ja, der er ikke rigtigt nok konkret i det 5. argument til at man egentlig kan sige noget for eller imod.
arne_v (34) skrev:public metode som kræver indsigt i arkitekturen ikke at kalde udenfor projekt => total fail i software dsign
Det var nu heller ikke det jeg mente. Det problem har vi ikke, det er DIG der ikke har indblik nok i arkitekturen til at kommentere den.
arne_v (34) skrev:public metode som har en fed blinkende note i dokumentationen om at den ikke kan kaldes udenfor projekt => workaround
Det problem har vi heller ikke.
arne_v (34) skrev:non public metode => the way
Ja, hvis det kunne lade sig gøre ville det passe mig okay. Men givet valget mellem noget der ikke engang compiler, og nogle metoder som ikke medfører nogen problemer at de er public, så synes jeg valget er nemt.
arne_v (35) skrev:Navngivning af metoder kan ikke løse et dokumentations behov.
Nu begynder du altså at vrøvle. Nogle gange er navngivning af metoder, klasser osv. tilstrækkelig dokumentation. Det ved enhver kompetent udvikler. Se evt. #13 igen.
Enhver kompetent udvikler ved også at ikke alt kan dokumenteres på den måde, det behøver du ikke argumentere for.
arne_v (35) skrev:Det duer ikke med OOP hvor et metodenavn tit vil være givet af et interface eller en virtuel/abstract metode som man overrider.
Det er dælme sjældent jeg ser det som et problem. Når jeg gør, så er det typisk fordi man er ved at gøre noget dumt.
Men ja, det sker da at man støder på det problem. Og selvfølgelig kan være nødt til at smide en kommentar ind i koden.
Det er ikke nogen undskyldning for ikke at gøre både den metode og al den anden kode så læsbar som muligt, hvilket overflødiggør meget dokumentation.
arne_v (36) skrev:Der bør stadigvæk være hurtigere altid at scrolle op og se doc fremfor at scrolle ned og se koden og hvis den så er non-triviel scrolle op igen og læse doc.
Nu forudsætter du metoder og forklaringer som er så store at der skal scrolles. Der vil jeg igen argumentere at man bør overveje refactoring i stedet for at dokumentere. Hvis det bliver så stort ofte, er der nok noget galt med kodestil eller udviklingsmiljø.
arne_v (36) skrev:Men derudover er det rimeligt standard idag (Eclipse og VS) at se docs ved mouseover. Og det virker også med kode hvor man kun har docs og ikke source installeret.
Personligt synes jeg et tryk på F3 er lige så nemt som at fiske efter en mouse-over. Især når den mouse-over skal suppleres med yderligere input for at få resten af dokumentationen frem.
Og det skal selvfølgelig også ses i forhold tli de mange timer det tager at skrive den dokumentation jeg argumenterer for at man springer over.
#39
Det tager jo netop ikke mange timer at skrive dokumentationen, hvis man skriver den løbene. Ihvertfald ikke helt så mange timer.
Problemet er når man for den dårlige vane ikke at gøre det. For så bliver det et møgsommeligt arbejde at gøre efter man har lavet det hele, og fået det til at virke, men det så måske er flere dage eller uger siden man sad med nogle af de enkelte dele.
Hvis man selv er den eneste udvikler i den del af koden, så er det sikkert rigeligt bare at skrive noterne i selve koden. Men det giver altså langt mere overblik at have det i en javadoc. Det som jeg udvikler i viser netop hvor vigtig den er, og der er den ikke voldsomt komplet. Men meget af den generere så også sig selv. Hvis man laver en function, så kommer den jo selv med det som fyldes i den funktion og referes til den når man begynder at bruge den.
Jeg tror egentlig mest dette er en forskellig fortolkning af hvad der menes af fuld dokumentation. Det behøves jo ikke at være et ringbind med et appendix og kildehenvisninger.
Men der skal jo gerne tilføjes f.eks. kildehenvisninger i documentationen vil jeg mene, hvis man tilføjer noget som man egentlig har lånt.
Et godt eksempel vil jeg mene er:
Taget fra AndEngine som jeg bruger. Så laver javadoc delen jo næsten sig selv, hvis man bare tilvænner sig denne fremgangs måde. Hvis jeg hiver javadoc info frem om den animate function, vil jeg få de parametre op som hvad de forskellige dele skal bruges til, og hvad meningen med dem er, selvom at de måske ser ud til at give sig selv for udvikleren.
God kode etik vil jeg kalde det. Men det er godt nok også 15 år siden jeg har fået egentlig direkte undervisning i kodning af en lære, og dengang var det Oascal og Delphi der blev arbejdet i. Kommentare var ikke helt nødvendigt på det niveau vi var på det år jeg havde programmering. Online guides giver desværre ikke helt de samme gode råd og tips som en lærer kan give, hvis han selv er professionel udvikler.
Dette er den slags jeg vurdere de mener med "fuld dokumentation". Selvom at den jo stort set skriver sig selv imens han bare udfylder de mest almindelige kommentare til sin kode.
Det tager jo netop ikke mange timer at skrive dokumentationen, hvis man skriver den løbene. Ihvertfald ikke helt så mange timer.
Problemet er når man for den dårlige vane ikke at gøre det. For så bliver det et møgsommeligt arbejde at gøre efter man har lavet det hele, og fået det til at virke, men det så måske er flere dage eller uger siden man sad med nogle af de enkelte dele.
Hvis man selv er den eneste udvikler i den del af koden, så er det sikkert rigeligt bare at skrive noterne i selve koden. Men det giver altså langt mere overblik at have det i en javadoc. Det som jeg udvikler i viser netop hvor vigtig den er, og der er den ikke voldsomt komplet. Men meget af den generere så også sig selv. Hvis man laver en function, så kommer den jo selv med det som fyldes i den funktion og referes til den når man begynder at bruge den.
Jeg tror egentlig mest dette er en forskellig fortolkning af hvad der menes af fuld dokumentation. Det behøves jo ikke at være et ringbind med et appendix og kildehenvisninger.
Men der skal jo gerne tilføjes f.eks. kildehenvisninger i documentationen vil jeg mene, hvis man tilføjer noget som man egentlig har lånt.
Et godt eksempel vil jeg mene er:
/**
* Animate specifics frames.
*
* @param pFrameDurations must have the same length as pFrames.
* @param pFrames indices of the frames to animate.
* @param pAnimationListener
*/
public void animate(final long[] pFrameDurations, final int[] pFrames, final IAnimationListener pAnimationListener) {
this.mAnimationData.set(pFrameDurations, pFrames);
this.initAnimation(pAnimationListener);
}
Taget fra AndEngine som jeg bruger. Så laver javadoc delen jo næsten sig selv, hvis man bare tilvænner sig denne fremgangs måde. Hvis jeg hiver javadoc info frem om den animate function, vil jeg få de parametre op som hvad de forskellige dele skal bruges til, og hvad meningen med dem er, selvom at de måske ser ud til at give sig selv for udvikleren.
God kode etik vil jeg kalde det. Men det er godt nok også 15 år siden jeg har fået egentlig direkte undervisning i kodning af en lære, og dengang var det Oascal og Delphi der blev arbejdet i. Kommentare var ikke helt nødvendigt på det niveau vi var på det år jeg havde programmering. Online guides giver desværre ikke helt de samme gode råd og tips som en lærer kan give, hvis han selv er professionel udvikler.
Dette er den slags jeg vurdere de mener med "fuld dokumentation". Selvom at den jo stort set skriver sig selv imens han bare udfylder de mest almindelige kommentare til sin kode.
kblood (40) skrev:Det tager jo netop ikke mange timer at skrive dokumentationen, hvis man skriver den løbene.
Det føles i hvert fald ikke som så lang tid. Men så mange gettere og settere som jeg laver, tager mange timer at dokumentere.
Eller jeg kan selvfølgelig bruges Eclipses default "sets the ..."/"gets the ..." template, men jeg kan ikke se formålet.
kblood (40) skrev:Problemet er når man for den dårlige vane ikke at gøre det.
Jeg synes også det er et problem at dokumentere som en dårlig vane. Jeg har set MANGE overflødige kommentarer, og flere der er decideret skadelige.
kblood (40) skrev:Men meget af den generere så også sig selv.
De javadoc-kommentarer som er autogenereret nytter absolut intet. Der KAN ikke stå mere, end der allerede står i koden.
Dokumentationen skal DU skrive. Dit IDE kan kun hjælpe dig med at stille det pænt op og overholde syntax.
kblood (40) skrev:Et godt eksempel vil jeg mene er:
Uden at kende sammenhængen ligner det umiddelbart udemærket dokumentation. Det ser også ud til at hvis man kender AndEngine kan man nemt gætte sig til det der står i dokumentationen, så der er ikke så meget at komme efter med refactoring.
Til gengæld ligner det en metode hvis formål er at være udstillet til andre systemer (fx. dit), hvilket gør det til et meget oplagt sted at dokumentere, og hellere for meget end for lidt.
illishar (30) skrev:(ref: Steve McConnell).
Nu du selv bringer ham på banen.
Citat fra starten af kapitlet "Self-Documenting Code":
Most programmers enjoy writing documentation if the documentation standards arenøt unreasonable. Like layout, good documentation is a sign of the professional pride a programmer puts into a program.
Jeg kan også anbefale at checke sektionen "To Comment or Not to Comment" og sammenligne argumenterne fra Callicles og Glaucon med argumenter fremført her (og konklusionen fra Socrates!).
Lad mig nu tage alt det jeg skrev og ikke kun det du selektivt udvalgte:
Siden du mener at koden i #13 er relevant som svar skal jeg vide om det er fordi at du mener at koden falder under "non-trivielle metoder" eller om det relaterer sig til interfaces?
Det er sjældent at du implementerer/overrider en metode hvor interfacet/den abstrakte basis klasse ikke har al relevant information?
Og det er dumt?
Jeg troede nærmest at det var kernen i OOP!
Hvilken refaktotering tænker du her på?
Hvis der skal scrolles for at læse doc, så er det vel næppe en god ide at putte informationen i metode navnet.
:-)
arne_v (35) skrev:
Navngivning af metoder kan ikke løse et dokumentations behov.
Af 2 årsager.
For non-trivielle metoder vil navnet blive for langt ved at putte informationen i navnet.
Det duer ikke med OOP hvor et metodenavn tit vil være givet af et interface eller en virtuel/abstract metode som man overrider.
myplacedk (39) skrev:
Nu begynder du altså at vrøvle. Nogle gange er navngivning af metoder, klasser osv. tilstrækkelig dokumentation. Det ved enhver kompetent udvikler. Se evt. #13 igen.
Siden du mener at koden i #13 er relevant som svar skal jeg vide om det er fordi at du mener at koden falder under "non-trivielle metoder" eller om det relaterer sig til interfaces?
myplacedk (39) skrev:Det er dælme sjældent jeg ser det som et problem. Når jeg gør, så er det typisk fordi man er ved at gøre noget dumt.
Det er sjældent at du implementerer/overrider en metode hvor interfacet/den abstrakte basis klasse ikke har al relevant information?
Og det er dumt?
Jeg troede nærmest at det var kernen i OOP!
myplacedk (39) skrev:Nu forudsætter du metoder og forklaringer som er så store at der skal scrolles. Der vil jeg igen argumentere at man bør overveje refactoring i stedet for at dokumentere. Hvis det bliver så stort ofte, er der nok noget galt med kodestil eller udviklingsmiljø.
Hvilken refaktotering tænker du her på?
Hvis der skal scrolles for at læse doc, så er det vel næppe en god ide at putte informationen i metode navnet.
:-)
arne_v (43) skrev:Siden du mener at koden i #13 er relevant som svar skal jeg vide om det er fordi at du mener at koden falder under "non-trivielle metoder" eller om det relaterer sig til interfaces?
Min påstand er STADIG at man med refactoring kan undgå MEGET dokumentation.
Jeg har ALDRIG påstået at man HELT kan undgå dokumentation af kode, derfor er det ikke den påstand jeg forsvarer, og jeg gik ud fra at det ikke var det du modargumenterede. Det var det åbenbart.
arne_v (43) skrev:Det er sjældent at du implementerer/overrider en metode hvor interfacet/den abstrakte basis klasse ikke har al relevant information?
Nej. Selv om metodernes navne er givet af interfaces, er klassens navn ikke. Hvis ikke du kan forklare klassens formål med klassens navn, så er der god sandsynlighed for at du skal refactor et eller andet. Det jeg typisk ser er at folk har glemt klassens formål, og har fået stoppet en masse ind der ikke hører til der. Pludselig er det en længere historie at forklare hvad klassen er til. Så synes jeg hellere de skal rydde op i koden.
arne_v (43) skrev:myplacedk (39) skrev:Nu forudsætter du metoder og forklaringer som er så store at der skal scrolles. Der vil jeg igen argumentere at man bør overveje refactoring i stedet for at dokumentere. Hvis det bliver så stort ofte, er der nok noget galt med kodestil eller udviklingsmiljø.
Hvilken refaktotering tænker du her på?
Dele op i mindre metoder, så man kan se dem uden at scrolle. Så store metoder gør ofte flere ting. Put dem i mindre metoder. Giv dem gode navne. Pludselig er den store uoverskuelige metode blevet til en lille metode som er nem at forstå uden dokumentation.
Det kan ikke altid lade sig gøre, men ofte.
arne_v (43) skrev:Hvis der skal scrolles for at læse doc, så er det vel næppe en god ide at putte informationen i metode navnet.
:-)
:-P
Hvis du dokumenterer hvad metoden gør, så er der nok noget galt. Koden beskriver hvad metoden gør. Er det ikke overskueligt, så ryd op. Hvis der er behov for at dokumenterer hvorfor metoden gør som den gør, så dokumenter endelig.
myplacedk (44) skrev:Jeg har ALDRIG påstået at man HELT kan undgå dokumentation af kode, derfor er det ikke den påstand jeg forsvarer, og jeg gik ud fra at det ikke var det du modargumenterede. Det var det åbenbart.
Jeg ville bare gerne vide hvordan dit eksempel i #13 relaterede sig til det jeg skrev.
Når du henviser til det eksempel som svar på noget jeg skriver, så antager jeg at det relaterer sig til dette.
myplacedk (44) skrev:Nej. Selv om metodernes navne er givet af interfaces, er klassens navn ikke. Hvis ikke du kan forklare klassens formål med klassens navn, så er der god sandsynlighed for at du skal refactor et eller andet. Det jeg typisk ser er at folk har glemt klassens formål, og har fået stoppet en masse ind der ikke hører til der. Pludselig er det en længere historie at forklare hvad klassen er til. Så synes jeg hellere de skal rydde op i koden.
Nu gik argumentet jo på metode navne og ikke på type navne.
Jeg har svært ved at se det at finde klassens navn som værende en god metode til at finde ud af hvad en metode gør.
myplacedk (44) skrev:
Dele op i mindre metoder, så man kan se dem uden at scrolle. Så store metoder gør ofte flere ting. Put dem i mindre metoder. Giv dem gode navne. Pludselig er den store uoverskuelige metode blevet til en lille metode som er nem at forstå uden dokumentation.
Det kan ikke altid lade sig gøre, men ofte.
????
Altså vi har en metode:
public void foobar() {
// 15 linier som gør a
// 15 linier som gør b
// 15 linier som gør c
}
og den refactorer vi til:
public void foobar() {
foobara();
foobarb();
foobarc();
}
private void foobara() {
// 15 linier som gør a
}
private void foobarb() {
// 15 linier som gør b
}
private void foobarc() {
// 15 linier som gør c
}
Det er en glimrende refactoring.
Men den mindsker da ikke dokumentations behovet for foobar !?!?
arne_v (45) skrev:Jeg ville bare gerne vide hvordan dit eksempel i #13 relaterede sig til det jeg skrev.
Som jeg forstår #11 argumenterer du for at kode som man tror ikke behøver dokumentation, bør dokumenteres alligevel. I #13 kommer jeg med et eksempel på en metode som jeg foretrækker IKKE at have dokumentation til, trods dine argumenter.
arne_v (45) skrev:Nu gik argumentet jo på metode navne og ikke på type navne.
Jeg troede vi snakkede navngivning generelt. Variabler, metoder, klasser, pakker...
arne_v (45) skrev:Jeg har svært ved at se det at finde klassens navn som værende en god metode til at finde ud af hvad en metode gør.
I konteksten hvor interfacet dikterer metodens navn, og man dermed ikke kan bruge navngivning til at differentiere implementeringerne?
public interface Command {
public void execute();
}
public class HentProduktlisteCommand {
public HentProduktlisteCommand() {
...
}
public void execute() {
...
}
}
Jeg vil gå ud fra at execute metoden henter en liste med produkter. I det system eksemplet kommer fra er det ikke så relevant at vide hvor det bliver gemt. Er man af en eller anden grund nysgerrig, så vil det jo stå i slutningen af execute-metoden. Det er ca. lige så hurtigt at slå op som at kigge i Javadoc'en. Forskellen i convenience opvejes rigeligt af risikoen for fejl i dokumentationen.
arne_v (45) skrev:public void foobar() {
foobara();
foobarb();
foobarc();
}
[...]
Men den mindsker da ikke dokumentations behovet for foobar !?!?
Jeg ser hellere ovenstående end:
/**
* foobarer så godt den kan. Det gør den ved at a, så b, og så c.
*/
public void foobar() {
// 15 linier som gør a
// 15 linier som gør b
// 15 linier som gør c
}
Det er dokumenteret lige godt, koden er bedre, der er ingen dokumentation som kan tage fejl. Man skal selvfølgelig huske at omdøbe de tre metoder hvis de laves om til at gøre noget andet, men det er nemmere at huske end at opdatere dokumentation. Rettelser i rækkefølge og parametre vil nok kunne gøres helt uden at tænke på dokumentation.
myplacedk (46) skrev:Som jeg forstår #11 argumenterer du for at kode som man tror ikke behøver dokumentation, bør dokumenteres alligevel. I #13 kommer jeg med et eksempel på en metode som jeg foretrækker IKKE at have dokumentation til, trods dine argumenter.
Ja - det er derfor jeg gerne vil vide hvordan dit eksempel i #13 relaterer sig til mine ragumenter i #35 som du svarede på i #39 ved at henvise til #13.
myplacedk (46) skrev:Jeg troede vi snakkede navngivning generelt. Variabler, metoder, klasser, pakker...
Ja.
Men vil du virkeligt mene at det at skulle checke typens navn for at forstå hvad en metode gør er godt?
Hvis ikke så er typens navn jo ikke relevant for lige netop denne del af tråden.
myplacedk (46) skrev:
I konteksten hvor interfacet dikterer metodens navn, og man dermed ikke kan bruge navngivning til at differentiere implementeringerne?
public interface Command {
public void execute();
}
public class HentProduktlisteCommand {
public HentProduktlisteCommand() {
...
}
public void execute() {
...
}
}
Jeg vil gå ud fra at execute metoden henter en liste med produkter. I det system eksemplet kommer fra er det ikke så relevant at vide hvor det bliver gemt. Er man af en eller anden grund nysgerrig, så vil det jo stå i slutningen af execute-metoden. Det er ca. lige så hurtigt at slå op som at kigge i Javadoc'en. Forskellen i convenience opvejes rigeligt af risikoen for fejl i dokumentationen.
Det mener du jo så altså.
Men jeg foretrækker godt nok at hold musen henover metode navnet og læse java doc fremfor at skulle scrolle op og finde typen.
myplacedk (46) skrev:Det er dokumenteret lige godt, koden er bedre, der er ingen dokumentation som kan tage fejl. Man skal selvfølgelig huske at omdøbe de tre metoder hvis de laves om til at gøre noget andet, men det er nemmere at huske end at opdatere dokumentation. Rettelser i rækkefølge og parametre vil nok kunne gøres helt uden at tænke på dokumentation.
Jeg synes stadig ikke at jeg kan se hvorfor dokumentations behovet er mindre ved at splitte den metode op. Man kan læse kode i begge tilfælde. Eller læse dokumentation.
arne_v (47) skrev:Men jeg foretrækker godt nok at hold musen henover metode navnet og læse java doc fremfor at skulle scrolle op og finde typen.
Ja, i den sammenhæng. Hvad så med denne:
taskManager.addTask(new Johanne());
Hvis man nu i stedet for at kalde den "Johanne" kaldte klassen "ResetCache", ville det så ikke være bedre end at dokumentere klassens execute-metode med teksten "Resets the cache"?
(Forudsat at det er tilstrækkelig dokumentation)
Opret dig som bruger i dag
Det er gratis, og du binder dig ikke til noget.
Når du er oprettet som bruger, får du adgang til en lang række af sidens andre muligheder, såsom at udforme siden efter eget ønske og deltage i diskussionerne.
- Forside
- ⟨
- Forum
- ⟨
- Tagwall
Gå til bund