Der er nogle gode eksempler på veldokumenteret kode derude, såsom java api. Men meget kode i offentlige projekter som git og interne projekter fra virksomheder er dårligt dokumenteret og ikke særlig nybegyndervenlig.

I alle mine softwareudviklingsperioder har jeg haft at gøre med dårligt dokumenteret kode. Jeg bemærkede følgende ting –

  1. Lidt eller ingen kommentarer i kode.
  2. Metode- og variabelnavne er ikke selvbeskrivende.
  3. Der er kun lidt eller ingen dokumentation for, hvordan koden passer ind i systemet eller forretningsprocesserne.
  4. Ansættelse af dårlige udviklere eller ikke vejledning af de gode. De kan ikke skrive enkel og ren kode. Derfor er det svært eller umuligt for nogen, herunder udvikleren, at dokumentere koden.

Som et resultat har jeg været nødt til at gennemgå en masse kode og tal med mange mennesker for at lære ting. Jeg føler, at det spilder alles tid. Det skaber også behovet for KT / vidensoverførselssessioner for nybegyndere til et projekt.

Jeg lærte, at dokumentation ikke får den opmærksomhed, den fortjener, af følgende årsager:

  1. Laziness.
  2. Udviklere kan ikke lide at gøre andet end kode.
  3. Jobsikkerhed. (Hvis ingen let kan forstå din kode, er du muligvis ikke let at udskifte.)
  4. Vanskelige deadlines giver lidt tid til at dokumentere.

Så jeg spekulerer på, om der er en måde at tilskynde til og håndhæve god dokumentationspraksis i en virksomhed eller et projekt. Hvad er strategierne skal bruges til at skabe anstændig dokumentation til ethvert projekts systemer og kode, uanset dets kompleksitet? Er der gode eksempler på, når der er behov for minimal eller ingen dokumentation?

IMHO, jeg føler, at vi skulle have en dokumentationsanmeldelse, efter at et projekt er leveret. Hvis det ikke er simpelt, kortfattet, illustrativt og brugervenligt, ejer udvikleren eller teknisk dokumentationsingeniør ansvaret for det og får det til at rette det. Jeg forventer heller ikke, at folk laver en række dokumenter håber ikke, at det vil være brugervenligt som de første bøger, men jeg forventer, at det eliminerer behovet for timers analyse og spild af KT-sessioner.

Er der en måde at afslutte eller lindre denne vanvid på? “Dokumentdrevet udvikling” måske?

Kommentarer

  • Der er en anden grund til, at der ofte ikke er nogen ordentlig dokumentation: Det er meget svært at skrive god dokumentation, der ikke ‘ t omformulerer bare koden på engelsk, men beskriver hvorfor koden er designet / skrevet på den måde. Behovet for disse oplysninger bliver først indlysende måneder efter at de skulle have været skrevet ned.
  • En anden alvorlig grund: mange udviklere har engelsk som andetsprog og / eller skriver engelsk dårligt . Du kan bare tvinge dem til at skrive en one-liner til en metode, men hvis du vil have god dokumentation, er du bedre klar til at betale for det og ansætte specialister til at gøre det.

Svar

Hvordan dokumenteres kode?

Du har allerede et tip: se på hvordan Java API er dokumenteret.

Mere generelt er der intet unikt sæt regler, der gælder for hvert projekt. Når jeg arbejder på forretningskritiske store projekter, har dokumentationen intet at gøre med den, jeg ville skrive til et lille open source-bibliotek, som igen ikke har noget at gøre med dokumentationen til mit mellemstore personlige projekt .

Hvorfor er mange open source-projekter ikke dokumenteret godt?

Fordi de fleste open source-projekter er lavet af folk, der bidrager til disse projekter, fordi det er sjovt. De fleste programmører og udviklere overvejer at skrivning af dokumentation ikke er sjovt nok til at blive gjort gratis.

Hvorfor mange lukkede kildeprojekter er ikke dokumenteret godt?

Fordi det koster en enorm sum penge at (1) skrive god dokumentation og at (2) vedligeholde den.

  1. Den øjeblikkelige omkostninger (omkostninger ved at skrive dokumentationen) er tydeligt synlige for interessenterne: Hvis dit team beder om at bruge de næste to måneder på at dokumentere projektet, er det to ekstra måneders løn at betale.

  2. Lo ng sigtomkostninger (omkostninger til vedligeholdelse af dokumentationen) bliver også bemærkelsesværdigt lette for lederne og er ofte det første mål, når de skal sænke omkostningerne eller forkorte forsinkelserne. Dette medfører et yderligere problem med forældet dokumentation, som hurtigt bliver ubrugelig og er ekstremt dyrt at opdatere.

  3. De langsigtede besparelser (besparelser ved ikke at skulle spilde et par dage på at udforske arvskode bare for at forstå en grundlæggende ting, som skulle have været dokumenteret for mange år siden) er på den anden side vanskelige at måle, hvilket bekræfter følelsen af nogle ledere, at skrivning og vedligeholdelse af dokumentation er spild af tid.

Det jeg ofte observerer er, at:

  1. I starten er teamet villig til at dokumentere meget.

  2. Over tid, pres af deadlines og manglende interesse gør det mere og mere vanskeligt at vedligeholde dokumentationen.

  3. Et par måneder senere kan en ny person, der praktisk tilslutter sig projektet, ikke bruge dokumentationen, fordi den overhovedet ikke svarer til det aktuelle system.

  4. Bemærk at ledelsen bebrejder udviklerne for ikke at vedligeholde dokumentationen udviklere beder om at bruge et par uger på at opdatere det.

    • Hvis ledelsen giver et par uger til det, gentages cyklussen.

    • Hvis ledelsen nægter, baseret på tidligere erfaring, øger det kun den dårlige oplevelse, da produktet mangler dokumentation, men der blev brugt et par måneder på at skrive og vedligeholde det.

Dokumentation skal være en kontinuerlig proces, ligesom testning. Brug en uge på bare at kode nogle få tusinder af LOC, og det er meget, meget smertefuldt at komme tilbage til test og dokumentation.

Sådan tilskyndes holdet til at skrive dokumentation?

På samme måde som måderne til at tilskynde folk til at skrive ren kode, til at foretage regelmæssig refactoring, bruge designmønstre eller tilføje nok enhedstests.

  • Led med et godt eksempel. Hvis du skriver god dokumentation, kan dine par muligvis også begynde at gøre det.

  • Lav systematiske kodevurderinger, herunder formelle kodevurderinger, der er målrettet til at inspicere dokumentationen.

  • Hvis nogle medlemmer af teamet er særligt antipatiske over for god dokumentation (eller overhovedet dokumentation), skal du diskutere emnet med dem privat for at forstå, hvilke hindringer der forhindrer dem i at skrive bedre dokumentation. Hvis de bebrejder manglen på tid, ser du kilden til problemerne.

  • Gør tilstedeværelsen eller manglen på dokumentation målbar i et par uger eller måneder, men ikke fokus på det. For eksempel kan du måle antallet af linjer med kommentarer pr. LOC, men gør det ikke til en permanent foranstaltning, ellers begynder udviklere at skrive lange men meningsløse kommentarer bare for at slippe af med lave score.

  • Brug gamification. Dette kommer sammen med det foregående punkt.

  • Brug positiv / negativ forstærkning .

  • (Se kommentaren fra SJuan76 ) Behandl manglen på kommentarer som fejl. For eksempel kan du i Visual Studio kontrollere en mulighed for at generere XML-dokumentation. Hvis du også kontrollerer, at alle advarsler behandles som fejl, vil manglen på en kommentar øverst i en klasse eller en metode stoppe kompileringen.

    Hvad angår de tre foregående punkter, skal denne bruges med forsigtighed. Jeg brugte det i et stykke tid med et særligt hårdt team af nybegynderprogrammerere, og det endte med StyleCop-kompatible kommentarer sådan: 

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

som var, hm …, ikke særlig nyttige.

Husk: intet automatiseret kan hjælpe dig med at lokalisere dårlige kommentarer, når programmører ønsker at skrue dig fast . Kun kode anmeldelser og andre menneskelige opgaver hjælper.

Er der gode eksempler på, når der er behov for minimal eller ingen dokumentation?

Dokumentation, der forklarer arkitekturen og designet , er ikke nødvendig:

  • For en prototype,

  • For et personligt projekt, der er skrevet om et par timer for at udføre en opgave, mens du er temmelig sikker på, at dette projekt ikke opretholdes længere,

  • For ethvert projekt, hvor det er indlysende, givet lille størrelse sammen med den særligt rene kode, at du bruger mere tid på at skrive dokumentation end alle fremtidige vedligeholdere, der udforsker koden.

Dokumentation inden for kode (kodekommentarer) er ikke nødvendig ifølge nogle udviklere, når koden er selvdokumenterende. For dem er tilstedeværelsen af kommentarer, undtagen i sjældne tilfælde, ikke et godt tegn, men et tegn på, at koden ikke blev omformuleret nok til at være klar uden behov for kommentarer.

Jeg mener, at vi skal gennemgå en dokumentation, når et projekt er leveret.

Hvis dit projekt leveres mindst en gang om ugen er det vejen at gå. Hvis dit projekt ikke er smidigt og leveres med intervaller på seks måneder, skal du foretage mere regelmæssige anmeldelser.

Kommentarer

  • Til ‘ hvordan man opmuntrer til ‘, vil jeg tilføje, at mange IDEer giver mulighed for meddelelse om manglende dokumentation som advarsler. Alternativt kan der muligvis foretages en statisk analyse af dokumentationen på OSB (selvfølgelig ville det alene ikke være nok).
  • @ SJuan76: Faktisk. Visual Studio kan endda behandle manglen på kommentarer som en kompileringstidsfejl. Jeg redigerede mit svar for at tilføje en note om det.
  • @ ArseniMourzenko – Jeg læste, at vi kunne opmuntre til en vis dokumentation i Agile ved at tilføje historier til dokumentation. Men disse bør ikke blokere for de andre historier, dvs. andre historier, definition af gjort, må ikke omfatte færdiggørelse af dokumentationshistorier. Hvordan lyder det?
  • @ArseniMourzenko – Jeg ‘ vil gerne tilføje yderligere to punkter til dit svar. (1) I Jira osv. Skal du tilføje en opgave til dokumentation hele tiden. (2) Få dokumenter gennemgået af 2 personer mere &, sæt det også som en opgave. På den måde vil folk blive mindet om at dokumentere & undgår at skrive dokumenter af lav kvalitet (på grund af gennemgang). Hvis du ikke ‘ ikke prioriterer det & gennemgår det, bliver det dårligt. Jeg ved, at Amazon laver en masse docs & doc-anmeldelser, måske lidt for meget.

Svar

Jeg synes, du skal skelne mellem kommentarer og dokumentation. Mens kommentarer er beskrivende, mangler de konsistens, de er spredt over hele koden. Kommentarer skal aldrig kompensere for kode, som ikke er tilstrækkelig selvbeskrivende, i stedet for at antyde andre programmører for vanskelige dele.

Hvorvidt kode skal dokumenteres, afhænger af projektets omfang. Der er helt sikkert mennesker, der mener, at alt skal dokumenteres, og det synes let at retfærdiggøre den tanke, for hvem ville tør modsætte sig dokumenterer viden? Heldigvis er softwareudvikling ikke videnskab, og verden kollapser ikke, hvis detaljerne bag dit lille program bliver uklare. Nu angående en professionel software til brug for mange udviklere, skal du selvfølgelig dokumentere din kode. Men hvis du er i positionen for at kode på det niveau, så ville du naturligvis vide det.

tl; dr

Hvis du beder om, at hvert projekt skal være veldokumenteret, så beder du for meget .

Kommentarer

  • Fortunately software development is not science Fortæl mig mere om, hvorfor du tror på dette.
  • @ Borat – Softwareudvikling er en ingeniørdisciplin, der indebærer, at den bruger de værktøjer, der leveres af science.
  • Jeg beder ikke alt om at blive dokumenteret. Det burde være lige nok til at give et højt overblik over, hvad et system og en kode gør. F.eks. fortæl mig, hvordan jeg bruger mit tv. Jeg er ‘ ligeglad med, om det bruger LCD, CRT, Vakuumrør eller Solid State-enheder for at få arbejdet gjort . Hvis en reparationsmand ønsker denne info, så lav separat dokumentation til ham.
  • Hvis du vil have et overblik på højt niveau, er identifikationsnavne nok. Ligesom knappen på dit tv muligvis har en ” På “. Så du beder om detaljer på lavt niveau.
  • @LeopoldAsperger: Jeg tror, Borat taler om at dokumentere arkitektur og design, ikke metoder i klasser.

Skriv et svar

Din e-mailadresse vil ikke blive publiceret. Krævede felter er markeret med *