Det finns några bra exempel på väldokumenterad kod där ute, till exempel java api. Men mycket kod i offentliga projekt som git och interna projekt från företag är dåligt dokumenterat och inte särskilt nykomlingvänligt.

I alla mina programvaruutvecklingsperioder har jag haft att göra med dåligt dokumenterad kod. Jag märkte följande saker –

  1. Lite eller inga kommentarer i koden.
  2. Metod- och variabelnamn beskrivs inte själv.
  3. Det finns liten eller ingen dokumentation för hur koden passar in i systemet eller affärsprocesserna.
  4. Anställa dåliga utvecklare eller inte mentorera de goda. De kan inte skriva enkel och ren kod. Därför är det svårt eller omöjligt för någon, inklusive utvecklaren att dokumentera koden.

Som ett resultat har jag varit tvungen att gå igenom en hel del kod och prata med många människor för att lära sig saker. Jag känner att det slösar bort all tid. Det skapar också behovet av KT / kunskapsöverföringssessioner för nykomlingar till ett projekt.

Jag lärde mig att dokumentation inte ges den uppmärksamhet den förtjänar på grund av följande skäl:

  1. Lata.
  2. Utvecklare gillar inte att göra annat än att koda.
  3. Arbetssäkerhet. (Om ingen lätt kan förstå din kod, kanske du inte lätt kan bytas ut.)
  4. Svåra deadlines ger lite tid att dokumentera.

Så jag undrar om det finns ett sätt att uppmuntra och genomdriva god dokumentationssed i ett företag eller projekt. Vilka är strategierna som ska användas för att skapa anständig dokumentation för alla projekts system och kod, oavsett dess komplexitet? Finns det några bra exempel på när minimal eller ingen dokumentation behövs?

IMHO, jag tycker att vi borde ha en dokumentationsgranskning efter att ett projekt har levererats. Om det inte är enkelt, kortfattat, illustrativt och användarvänligt, äger utvecklaren eller teknisk dokumentationsingenjör ansvaret för det och görs att fixa det. Jag förväntar mig inte heller att folk ska göra en del dokumentation, hoppas inte att det kommer att vara användarvänligt som de första böckerna, men jag förväntar mig att det eliminerar behovet av timmar med analys och slösaktiga KT-sessioner.

Finns det ett sätt att avsluta eller lindra denna galenskap? ”Dokumentdriven utveckling” kanske?

Kommentarer

  • Det finns en annan anledning till att det ofta inte finns någon ordentlig dokumentation: Det är mycket svårt att skriva bra dokumentation som inte ’ omformulerar inte bara koden på engelska, men beskriver varför koden är utformad / skriven på det sättet. Behovet av denna information blir först uppenbart månader efter att den borde ha skrivits ner.
  • En annan allvarlig anledning: många utvecklare har engelska som andraspråk och / eller skriver engelska dåligt . Du kan bara tvinga dem att skriva en one-liner för en metod, men om du vill ha bra dokumentation är du bättre beredd att betala för det och anställa specialister för att göra det.

Svar

Hur dokumenterar jag kod?

Du har redan en ledtråd: titta på hur Java API är dokumenterat.

Mer allmänt finns det inga unika regler som gäller för varje projekt. När jag arbetar med affärskritiska storskaliga projekt har dokumentationen ingenting att göra med den jag skulle skriva för ett litet open source-bibliotek, vilket i sin tur inte har något att göra med dokumentationen för mitt medelstora personliga projekt .

Varför många open source-projekt är inte dokumenterade väl?

Eftersom de flesta open source-projekt är gjorda av människor som bidrar till dessa projekt eftersom det är roligt. De flesta programmerare och utvecklare anser att skrivdokumentation inte är tillräckligt roligt för att kunna göras gratis.

Varför många projekt med slutna källor är inte dokumenterade väl?

Eftersom det kostar en enorm summa pengar att (1) skriva bra dokumentation och att (2) underhålla den.

  1. Det omedelbara kostnad (kostnad för att skriva dokumentationen) är tydligt synlig för intressenterna: om ditt team ber att spendera de kommande två månaderna på att dokumentera projektet är det ytterligare två månaders lön att betala.

  2. Lo ng termkostnad (kostnad för underhåll av dokumentationen) blir märkbar ganska lätt också för cheferna och är ofta det första målet när de måste sänka kostnaden eller förkorta förseningarna. Detta orsakar ett ytterligare problem med föråldrad dokumentation som snabbt blir värdelös och är extremt dyrt att uppdatera.

  3. De långsiktiga besparingarna (besparingar från att inte behöva slösa bort några dagar på att utforska arvskod bara för att förstå en grundläggande sak som borde ha dokumenterats för flera år sedan) är å andra sidan svåra att mäta, vilket bekräftar känslan hos vissa chefer att skriva och underhålla dokumentation är slöseri med tid.

Det jag ofta observerar är att:

  1. I början är teamet villigt att dokumentera mycket.

  2. Med tiden gör press av tidsfrister och brist på intresse allt svårare att underhålla dokumentationen.

  3. Några månader senare kan en ny person som praktiskt taget ansluter sig till projektet inte använda dokumentationen, för den överensstämmer inte alls med det aktuella systemet.

  4. Att lägga märke till att ledningen klandrar utvecklare för att inte underhålla dokumentationen, utvecklare ber att spendera några veckor på att uppdatera det.

    • Om ledningen ger några veckor för det upprepas cykeln.

    • Om ledningen vägrar, baserat på tidigare erfarenheter, ökar det bara den dåliga upplevelsen, eftersom produkten saknar dokumentation, men några månader spenderades på att skriva och underhålla den.

Dokumentation bör vara en kontinuerlig process, precis som testning. Tillbringa en vecka med att bara koda några tusen LOC, och det är väldigt, mycket smärtsamt att komma tillbaka till tester och dokumentation.

Hur man uppmuntrar teamet att skriva dokumentation?

På samma sätt som att uppmuntra människor att skriva ren kod, att göra regelbunden refactoring, att använda designmönster eller att lägga till tillräckligt med enhetstester.

  • Föregå med gott exempel. Om du skriver bra dokumentation kan dina par också börja göra det.

  • Gör systematiska kodgranskningar, inklusive formella kodgranskningar som är inriktade på att inspektera dokumentationen.

  • Om vissa medlemmar i teamet är särskilt antipatiska mot bra dokumentation (eller alls dokumentation), diskutera ämnet med dem privat för att förstå vilka hinder som hindrar dem från att skriva bättre dokumentation. Om de skyller på bristen på tid ser du källan till problemen.

  • Gör närvaron eller bristen på dokumentation mätbar i några veckor eller månader, men inte fokusera på det. Du kan till exempel mäta antalet rader med kommentarer per LOC, men gör det inte till ett permanent mått, annars kommer utvecklare att börja skriva långa men meningslösa kommentarer bara för att bli av med låga poäng.

  • Använd gamification. Detta överensstämmer med föregående punkt.

  • Använd positiv / negativ förstärkning .

  • (Se kommentaren från SJuan76 ) Behandla avsaknaden av kommentarer som fel. I Visual Studio kan du till exempel kontrollera ett alternativ för att generera XML-dokumentation. Om du också kontrollerar att alla varningar behandlas som fel, kommer bristen på en kommentar högst upp i en klass eller en metod att stoppa sammanställningen.

    När det gäller de tre föregående punkterna bör den här användas med försiktighet. Jag använde den ett tag med ett särskilt tufft team av nybörjare och det slutade med StyleCop-kompatibla kommentarer så här: 

  /// <summary> /// Gets or sets the PrimaryHandling. /// </summary> public Workflow PrimaryHandling { get; set; }

som var, hm …, inte särskilt hjälpsamma.

Kom ihåg: ingenting automatiskt kan hjälpa dig att hitta dåliga kommentarer när programmerare vill klara sig med dig . Endast kod recensioner och andra mänskliga uppgifter hjälper.

Finns det några bra exempel på när minimal eller ingen dokumentation behövs?

Dokumentation som förklarar arkitekturen och designen behövs inte:

  • För en prototyp,

  • För ett personligt projekt skrivet på några timmar för att utföra en uppgift, samtidigt som du är ganska säker på att projektet inte kommer att upprätthållas längre,

  • För alla projekt där det är uppenbart, med tanke på liten storlek, tillsammans med den särskilt rena koden, att du kommer att spendera mer tid på att skriva dokumentation än alla framtida underhållare som utforskar koden.

Dokumentation i kod (kodkommentarer) behövs inte enligt vissa utvecklare när koden är självdokumenterande. För dem är närvaron av kommentarer, förutom i sällsynta fall, inte ett bra tecken, utan ett tecken på att koden inte reflekterades tillräckligt för att vara tydlig utan behov av kommentarer.

Jag tycker att vi bör granska en dokumentation efter att ett projekt har levererats.

Om ditt projekt levereras åtminstone en gång i veckan är det vägen att gå. Om ditt projekt inte är smidigt och levereras med sex månaders mellanrum, gör sedan mer regelbundna recensioner.

Kommentarer

  • Till ’ hur man uppmuntrar ’, jag skulle tillägga att många IDE tillåter meddelande om saknad dokumentation som varningar. Alternativt kan en statisk analys av dokumentationen göras på OSB (naturligtvis skulle det inte vara tillräckligt).
  • @ SJuan76: Ja. Visual Studio kan till och med behandla bristen på kommentarer som ett kompileringsfel. Jag redigerade mitt svar för att lägga till en anteckning om det.
  • @ ArseniMourzenko – Jag läste att vi kunde uppmuntra lite dokumentation i Agile genom att lägga till historier för dokumentation. Men dessa bör inte blockera de andra berättelserna, dvs andra berättelser definition av gjort, får inte innehålla komplettering av dokumentationsberättelser. Hur låter det?
  • @ArseniMourzenko – Jag ’ vill lägga till ytterligare två punkter i ditt svar. (1) I Jira etc., lägg till en uppgift för dokumentation hela tiden. (2) Låt några dokument granskas av ytterligare 2 personer & sätta det som en uppgift också. På det sättet kommer människor att påminnas om att dokument & undviker att skriva dokument av låg kvalitet (på grund av granskning). Om du inte ’ inte prioriterar det & granskar det det blir dåligt. Jag vet att Amazon gör en hel del dokument & doc-recensioner, kanske lite för mycket.

Svar

Jag tycker att du bör skilja mellan kommentarer och dokumentation. Kommentarer är beskrivande, men de saknar konsistens, de är utspridda över hela koden. Kommentarer ska aldrig kompensera för kod som inte är tillräckligt självbeskrivande, utan bör antyda andra programmerare till knepiga delar.

Huruvida koden ska dokumenteras beror på projektets omfattning. Visst finns det människor som tror att allt bör dokumenteras, och det verkar lätt att motivera den tanken för vem skulle våga motsätta sig dokumentera kunskap? Lyckligtvis är mjukvaruutveckling inte vetenskap, och världen kollapsar inte om detaljerna bakom ditt lilla program blir dunkla. Nu rörande en professionell programvara för användning av många utvecklare, ja självklart borde du dokumentera din kod. Men om du är i positionen för att koda på den nivån, då skulle du uppenbarligen veta det.

tl; dr

Om du ber om att varje projekt ska vara väl dokumenterat, ber du för mycket .

Kommentarer

  • Fortunately software development is not science Snälla berätta mer om varför du tror på det.
  • @ Borat – Mjukvaruutveckling är en ingenjörsdisciplin, vilket innebär att den använder de verktyg som tillhandahålls av science.
  • Jag ber inte att allt ska dokumenteras. Det borde vara precis tillräckligt för att ge en överblick över vad ett system och en kod gör. Exempel. Berätta hur jag använder min TV. Jag bryr mig inte ’ om den använder LCD, CRT, Vakuumrör eller halvledarenheter för att få jobbet gjort . Om en reparationsman vill ha den informationen, gör sedan separat dokumentation för honom.
  • Om du vill ha en översikt på hög nivå räcker det med identifieringsnamn. Precis som knappen på din TV kan ha en ” På ” -etiketten. Så du ber om detaljer på låg nivå.
  • @LeopoldAsperger: Jag tror att Borat pratar om att dokumentera arkitektur och design, inte metoder i klasser.

Lämna ett svar

Din e-postadress kommer inte publiceras. Obligatoriska fält är märkta *