8 svar · 3 867 visningar · startad av Pedda
Den här frågan riktar sig egentligen till er som jobbar som utvecklare inom .NET.
Anledningen är att jag funderar på hur jag kan förbättra mina rutiner för hur jag dokumenterar koden när jag jobbar i olika projekt.
Idag använder jag xml kommentarer i koden och gör en output (XML documentation file). Givetvis gör jag även en del andra kommentarer som inte är xml kommentarer.
Men sen så gör jag inte så mycket mer, XML filen ligger oftast bara och skräpar och jag gör ingen annan output med hjälp av sandcastle eller liknande.
Så... hur gör ni?
Jag dokumenterar inte, eller inte i de flesta fallen iallafall, jag håller helt och hållet med Robert Steve Martin som påstår att behöver man kommentera sin kod så har du gjort något fel.
Klassnamnet, metodnamnet och variablerna säger i 98% av fallen vad koden gör.
Håller man klasserna(ca max 200 rader) och metoderna korta(2-6 rader). Så får man självbeskrivande kod Separation of Concerns =).
Clean Code boken är ett måste att läsa.
Klassnamnet, metodnamnet och variablerna säger i 98% av fallen vad koden gör.
Håller man klasserna(ca max 200 rader) och metoderna korta(2-6 rader). Så får man självbeskrivande kod Separation of Concerns =).
Ja, bra kod säger vad klassen/metoden gör. Men en kort beskrivning över en komplicerad klass/metod säger även vad koden är tänkt att göra och hur den är tänkt att användas. Men oftast håller jag med dig - om koden är trivial behövs inget annat.
Som sagt i 2% av fallen då :)
i 98% av fallen så bör ju metodnamnet avslöja det som står i beskrivningen
eller metodanropen inuti den... Samma sak med klass
Säg att metodanropsnamnen inuti den består av större delen av meningarna i kommentarerna.
Samma sak med klassnamn och metodnamnen inuti den.
Men i vissa specialfall kan det vara bra med kommentar. Dock aldrig inuti en metod.
Nej, that's a load of bull (till viss del ;)).
Jag skulle vilja påstå att det beror på vad man programmerar. Utvecklar man ett API av något slag, så skulle jag säga att dokumentation måste finnas tillgänglig. Jag tror ju inte på att Nickemannen och erciz sitter och läser igenom själva koden för ett API dom ska använda, utan snarare en dokumentation kring API:et och hur det fungerar. Enda sättet att dokumentera kod är ju inte att skriva kommentarer rakt i källkodsfilen heller... Tänk "MSDN" - tänk om inte Microsoft hade dokumenterat sin kod ;)
Sitter man däremot och gör ett backend till en webbsida i MVC3, så kan jag hålla med om att dokumentation till viss/stor del är överflödig. Men att generalisera så mycket som ni gör är farligt, för dokumenterad kod är fruktansvärt mycket enklare att hantera än icke dokumenterad.
Nu kan jag inte svara fullt ut på Peddas fråga, då jag inte sitter speciellt mycket i .NET. Har suttit mest med EPi Server, och då blir det ett fåtal kommentarer kring templates eller moduler, men väldigt sällan i själva code behind-filerna.
Håller med om, och använder mig av förklarande klassnamn och metodnamn osv.
Kan förstå om man inte dokumenterar så mycket om man t.ex bygger en hemsida.
I mitt fall så handlar det oftast om desktop applikationer och services för manipulering av data mellan olika system. Ofta genom användande av de olika systemens api'er.
Dokumentationen är inte till användare, utan till andra utvecklare som eventuellt jobbar i projektet eller för framtida utvecklare som ska bygga vidare.
T.ex innehåller xml dokumentationen inte bara en kort beskrivning av t.ex metoden, utan även information om vem som senast uppdaterat mm.
Så xml dokumentation exporteras alltså varje gång man kompilerar och kan användas utanför källkoden.
Jag trodde att jag var dålig på att dokumentera koden för hantering externt, men det kanske är tvärtom. :o
Ja, det är väl oftast sån genererad kod som brukar användas för API:er. Jag har mest använt Java och där har ju nästan alla API:er genererad dokumentation från JavaDoc-kod ovanför metoderna.
Nej, that's a load of bull (till viss del ;)).
Jag skulle vilja påstå att det beror på vad man programmerar. Utvecklar man ett API av något slag, så skulle jag säga att dokumentation måste finnas tillgänglig. Jag tror ju inte på att Nickemannen och erciz sitter och läser igenom själva koden för ett API dom ska använda, utan snarare en dokumentation kring API:et och hur det fungerar. Enda sättet att dokumentera kod är ju inte att skriva kommentarer rakt i källkodsfilen heller... Tänk "MSDN" - tänk om inte Microsoft hade dokumenterat sin kod ;)
Sitter man däremot och gör ett backend till en webbsida i MVC3, så kan jag hålla med om att dokumentation till viss/stor del är överflödig. Men att generalisera så mycket som ni gör är farligt, för dokumenterad kod är fruktansvärt mycket enklare att hantera än icke dokumenterad.
Nu kan jag inte svara fullt ut på Peddas fråga, då jag inte sitter speciellt mycket i .NET. Har suttit mest med EPi Server, och då blir det ett fåtal kommentarer kring templates eller moduler, men väldigt sällan i själva code behind-filerna.
Som sagt 98% jag tror inte alla sitter och skriver apikod.
Och i de flesta fallen när jag skriver i .net, nu har jag lärt mig så brukar jag anvädan intellisensen och sedan gå till msdn. Och jag kommer till msdn så år det någon konfigurationsgrej om det inte är det så är det fail att dom itne srkivit något tillräckligt bra api som gör att jag fattar.
Jag brukar inte behöva läsa den förklarande texten även om jag gör det ibland. Att dokumentera när man är tredjepartsleverantör kan jag hålla med om att man kan.
Och självklart kan det finnas dokumentation om man jobbar i projekt där man inte skall vara tredjepartsleverantör men isf ser jag det mer som designspecifikation där man beskriver i det stora hela hur arkitekturen ser ut.
Av någon anledning har jag alltid en txt-fil öppen vid sidan av som jag för anteckningar i.
Som flera har sagt, så känns kommentarer överflödiga i 98% av koden. Dock så brukar jag kommentera i stort sett alla klasser, funktioner och metoder innan jag "lämnar bort" koden.
