Det er noen gode eksempler på veldokumentert kode der ute, for eksempel java api. Men mye kode i offentlige prosjekter som git og interne prosjekter fra selskaper er dårlig dokumentert og ikke veldig nykommervennlig.

I alle mine programvareutviklingsperioder har jeg måttet håndtere dårlig dokumentert kode. Jeg la merke til følgende ting –

  1. Lite eller ingen kommentarer i koden.
  2. Metode- og variabelnavn er ikke selvbeskrivende.
  3. Det er liten eller ingen dokumentasjon for hvordan koden passer inn i systemet eller forretningsprosessene.
  4. Ansette dårlige utviklere eller ikke veilede de gode. De kan ikke skrive enkel og ren kode. Derfor er det vanskelig eller umulig for noen, inkludert utvikleren å dokumentere koden.

Som et resultat har jeg måttet gå gjennom mange kode og snakk med mange mennesker for å lære ting. Jeg føler dette kaster bort alles tid. Det skaper også behovet for KT / kunnskapsoverføringsøkter for nykommere i et prosjekt.

Jeg lærte at dokumentasjon ikke gis den oppmerksomheten den fortjener på grunn av følgende grunner:

  1. Latskap.
  2. Utviklere liker ikke å gjøre noe annet enn å kode.
  3. Jobbsikkerhet. (Hvis ingen kan forstå koden din lett, er du kanskje ikke lett å bytte ut.)
  4. Vanskelige tidsfrister gir lite tid til å dokumentere.

Så jeg lurer på om det er en måte å oppmuntre til og håndheve god dokumentasjonspraksis i et selskap eller prosjekt. Hva er strategiene skal brukes til å lage anstendig dokumentasjon for systemene og koden til ethvert prosjekt, uavhengig av dets kompleksitet? Er det noen gode eksempler på når minimal eller ingen dokumentasjon er nødvendig?

IMHO, jeg føler at vi burde ha en dokumentasjonsgjennomgang etter at et prosjekt er levert. Hvis det ikke er enkelt, kortfattet, illustrerende og brukervennlig, eier utvikleren eller teknisk dokumentasjonsingeniør ansvaret for det og får det til å fikse det. Jeg forventer heller ikke at folk lager dokumentasjon, håper ikke at det vil være brukervennlig som de første bøkene, men jeg forventer at det vil eliminere behovet for timer med analyse og bortkastede KT-økter.

Er det en måte å avslutte eller lindre denne galskapen på? «Dokumentdrevet utvikling» kanskje?

Kommentarer

  • Det er en annen grunn til at det ofte ikke er skikkelig dokumentasjon: Det er veldig vanskelig å skrive god dokumentasjon som ikke ‘ t bare omskriver koden på engelsk, men beskriver hvorfor koden er designet / skrevet på den måten. Behovet for denne informasjonen blir først åpenbart måneder etter at den burde vært skrevet ned.
  • En annen alvorlig grunn: mange utviklere har engelsk som andrespråk og / eller skriver engelsk dårlig. . Du kan bare tvinge dem til å skrive en one-liner for en metode, men hvis du vil ha god dokumentasjon, er du bedre forberedt på å betale for det, og leie spesialister til å gjøre det.

Svar

Hvordan dokumentere kode?

Du har allerede et hint: se på hvordan Java API er dokumentert.

Mer generelt er det ikke noe unikt sett med regler som gjelder for hvert prosjekt. Når jeg jobber med forretningskritiske prosjekter i stor skala, har dokumentasjonen ingenting å gjøre med den jeg vil skrive for et lite open source-bibliotek, som igjen ikke har noe å gjøre med dokumentasjonen til mitt mellomstore personlige prosjekt .

Hvorfor er mange åpen kildekode-prosjekter ikke godt dokumentert?

Fordi de fleste open source-prosjekter er laget av folk som bidrar til disse prosjektene fordi det er morsomt. De fleste programmerere og utviklere vurderer at skrivedokumentasjon ikke er morsomt nok til å gjøres gratis.

Hvorfor mange lukkede kildeprosjekter er ikke dokumentert godt?

Fordi det koster enorme mengder penger å (1) skrive god dokumentasjon og å (2) vedlikeholde den.

  1. Det umiddelbare kostnadene (kostnadene ved å skrive dokumentasjonen) er tydelig for interessentene: Hvis teamet ditt ber om å bruke de neste to månedene på å dokumentere prosjektet, er det to ekstra måneders lønn å betale.

  2. Lo ng terminkostnad (kostnad for vedlikehold av dokumentasjonen) blir merkbar ganske lett for lederne, og er ofte det første målet når de må redusere kostnadene eller forkorte forsinkelsene. Dette medfører et ekstra problem med utdatert dokumentasjon som raskt blir ubrukelig, og som er ekstremt dyrt å oppdatere.

  3. De langsiktige besparelsene (besparelser fra å slippe å kaste bort noen dager på å utforske arvskode bare for å forstå en grunnleggende ting som burde vært dokumentert for mange år siden) er derimot vanskelig å måle, noe som bekrefter følelsen til noen ledere at det å skrive og vedlikeholde dokumentasjon er bortkastet tid.

Det jeg ofte observerer er at:

  1. I begynnelsen er teamet villig til å dokumentere mye.

  2. Over tid, press av tidsfrister og manglende interesse gjør det vanskeligere og vanskeligere å opprettholde dokumentasjonen.

  3. Noen få måneder senere kan en ny person som tilsluttes prosjektet praktisk talt ikke bruke dokumentasjonen, fordi den i det hele tatt ikke samsvarer med det faktiske systemet.

  4. Legg merke til at ledelsen gir utviklerne skylden for ikke å opprettholde dokumentasjonen; utviklere ber om å bruke noen uker på å oppdatere den.

    • Hvis ledelsen gir noen uker til det, gjentas syklusen.

    • Hvis ledelsen nekter, basert på tidligere erfaring, øker det bare den dårlige opplevelsen, siden produktet mangler dokumentasjon, men noen måneder ble brukt til å skrive og vedlikeholde det.

Dokumentasjon bør være en kontinuerlig prosess, akkurat som testing. Bruk en uke på å kode noen få tusenvis av LOC, og det er veldig, veldig vondt å komme tilbake til tester og dokumentasjon.

Hvordan oppmuntre teamet til å skrive dokumentasjon?

På samme måte som måter å oppmuntre folk til å skrive ren kode, til å gjøre regelmessig refactoring, bruke designmønstre eller legge til nok enhetstester.

  • Led med et godt eksempel. Hvis du skriver god dokumentasjon, kan det hende parene dine begynner å gjøre det også.

  • Gjør systematiske kodevurderinger, inkludert formelle kodevurderinger som er rettet mot å inspisere dokumentasjonen.

  • Hvis noen av teamets medlemmer er spesielt antipatiske mot god dokumentasjon (eller i det hele tatt dokumentasjon), kan du diskutere emnet med dem privat for å forstå hva som er hindringene som hindrer dem i å skrive bedre dokumentasjon. Hvis de skylder på mangel på tid, ser du kilden til problemene.

  • Gjør tilstedeværelsen eller mangelen på dokumentasjon målbar i noen uker eller måneder, men ikke fokus på det. For eksempel kan du måle antall linjer med kommentarer per LOC, men ikke gjøre det til et permanent mål, ellers vil utviklere begynne å skrive lange men meningsløse kommentarer bare for å bli kvitt lave score.

  • Bruk gamification. Dette kommer sammen med forrige punkt.

  • Bruk positiv / negativ forsterkning .

  • (Se kommentaren fra SJuan76 ) Behandle mangelen på kommentarer som feil. I Visual Studio kan du for eksempel sjekke et alternativ for å generere XML-dokumentasjon. Hvis du også sjekker at alle advarsler blir behandlet som feil, vil mangelen på en kommentar øverst i en klasse eller en metode stoppe samlingen.

    Når det gjelder de tre forrige punktene, bør denne brukes med forsiktighet. Jeg brukte den en stund med et spesielt tøft team av nybegynnere, og det endte med StyleCop-kompatible kommentarer sånn: 

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

som var, hm …, ikke spesielt nyttige.

Husk: ingenting automatisert kan hjelpe deg med å finne dårlige kommentarer når programmerere vil gjøre noe med deg . Bare kode anmeldelser og andre menneskelige oppgaver vil hjelpe.

Er det noen gode eksempler på når minimal eller ingen dokumentasjon er nødvendig?

Dokumentasjon som forklarer arkitekturen og designet er ikke nødvendig:

  • For en prototype,

  • For et personlig prosjekt skrevet om noen timer for å utføre en oppgave, mens du er ganske sikker på at dette prosjektet ikke blir opprettholdt lenger,

  • For ethvert prosjekt der det er åpenbart, gitt liten størrelse på den, kombinert med den spesielt rene koden, at du vil bruke mer tid på å skrive dokumentasjon enn alle fremtidige vedlikeholdere på å utforske koden.

Dokumentasjon i kode (kodekommentarer) er ikke nødvendig i følge noen utviklere når koden er selvdokumenterende. For dem er tilstedeværelsen av kommentarer, bortsett fra i sjeldne tilfeller, ikke et godt tegn, men et tegn på at koden ikke ble omformet nok til å være klar uten behov for kommentarer.

Jeg føler at vi bør ha en dokumentasjonsgjennomgang etter at et prosjekt er levert.

Hvis prosjektet ditt leveres minst en gang i uken er det veien å gå. Hvis prosjektet ditt ikke er smidig og blir levert med seks måneders mellomrom, gjør du mer regelmessige gjennomganger.

Kommentarer

  • Til ‘ hvordan man kan oppmuntre til ‘, vil jeg legge til at mange IDEer tillater varsling om manglende dokumentasjon som advarsler. Alternativt kan en statisk analyse av dokumentasjonen gjøres på OSB (selvfølgelig ville det ikke være nok).
  • @ SJuan76: Faktisk. Visual Studio kan til og med behandle mangelen på kommentarer som en kompileringstidsfeil. Jeg redigerte svaret mitt for å legge til et notat om det.
  • @ ArseniMourzenko – Jeg leste at vi kunne oppmuntre til litt dokumentasjon i Agile ved å legge til historier for dokumentasjon. Men disse bør ikke blokkere de andre historiene, dvs. andre historiedefinisjoner av gjort, må ikke inkludere fullføring av dokumentasjonshistorier. Hvordan høres det ut?
  • @ArseniMourzenko – Jeg ‘ vil legge til to poeng til i svaret ditt. (1) I Jira etc., legg til en oppgave for dokumentasjon hele tiden. (2) Få dokumenter gjennomgått av 2 personer til &, legg det også som en oppgave. På den måten vil folk bli påminnet om å dokumentere & for å unngå å skrive dokumenter av lav kvalitet (på grunn av gjennomgang). Hvis du ikke ‘ ikke prioriterer det & vurderer det, så blir det dårlig. Jeg vet at Amazon gjør mange dokumenter & doc-anmeldelser, kanskje litt for mye.

Svar

Jeg synes du bør skille mellom kommentarer og dokumentasjon. Selv om kommentarer er beskrivende, mangler de konsistens, de er spredt over hele koden. Kommentarer skal aldri kompensere for kode som ikke er selvbeskrivende nok, i stedet bør den antyde andre programmerere på vanskelige deler.

Hvorvidt koden skal dokumenteres, avhenger av prosjektets omfang. Det er sikkert folk som mener at alt skal dokumenteres, og det virker lett å rettferdiggjøre den tanken fordi hvem ville våge å motsette seg dokumentere kunnskap? Heldigvis er ikke programvareutvikling vitenskap, og verden kollapser ikke hvis detaljene bak det lille programmet ditt blir uklare. Nå angående en profesjonell programvare for bruk av mange utviklere, ja selvfølgelig bør du dokumentere koden din. Men hvis du er i posisjonen for å kode på det nivået, så ville du tydeligvis vite det.

tl; dr

Hvis du ber om at hvert prosjekt skal være godt dokumentert, spør du for mye .

Kommentarer

  • Fortunately software development is not science Fortell meg mer om hvorfor du tror dette.
  • @ Borat – Programvareutvikling er en ingeniørfag, som innebærer at den bruker verktøyene fra science.
  • Jeg ber ikke om at alt skal dokumenteres. akkurat nok til å gi et høyt nivå oversikt over hva et system og en kode gjør. F.eks. Fortell meg hvordan jeg bruker TV-en. Jeg bryr meg ikke ‘ om den bruker LCD, CRT, Vakuumrør eller halvledere for å få jobben gjort . Hvis en reparasjonsmann vil ha den informasjonen, må du lage egen dokumentasjon for ham.
  • Hvis du vil ha en oversikt på høyt nivå, er identifikasjonsnavn nok. Akkurat som knappen på TV-en din kan ha en » På » -etiketten. Så du ber om detaljer på lavt nivå.
  • @LeopoldAsperger: Jeg tror Borat snakker om å dokumentere arkitektur og design, ikke metoder i klasser.

Legg igjen en kommentar

Din e-postadresse vil ikke bli publisert. Obligatoriske felt er merket med *