Er zijn een aantal goede voorbeelden van goed gedocumenteerde code, zoals java api. Maar veel code in openbare projecten zoals GIT en interne projecten van bedrijven is slecht gedocumenteerd en niet erg nieuwkomersvriendelijk.

In al mijn softwareontwikkelingsstints heb ik te maken gehad met slecht gedocumenteerde code. Ik merkte de volgende dingen op –

  1. Weinig of geen commentaar in de code.
  2. De namen van methoden en variabelen zijn niet zelfbeschrijvend.
  3. Er is weinig of geen documentatie over hoe de code in het systeem of de bedrijfsprocessen past.
  4. Slechte ontwikkelaars inhuren of de goede niet begeleiden. Ze kunnen geen simpele en schone code schrijven. Daarom is het moeilijk of onmogelijk voor iedereen, inclusief de ontwikkelaar, om de code te documenteren.

Als gevolg daarvan heb ik veel programmeer en praat met veel mensen om dingen te leren. Ik voel dat dit ieders tijd verspilt. Het creëert ook de behoefte aan KT / Knowledge-overdrachtssessies voor nieuwkomers in een project.

Ik heb geleerd dat documentatie niet de aandacht krijgt die het verdient vanwege de volgende redenen:

  1. Luiheid.
  2. Ontwikkelaars houden er niet van om iets anders te doen dan code.
  3. Werkzekerheid. (Als niemand je code gemakkelijk kan begrijpen, ben je misschien niet gemakkelijk te vervangen.)
  4. Moeilijke deadlines laten weinig tijd over om te documenteren.

Dus ik vraag me af of er een manier is om goede documentatiepraktijken in een bedrijf of project aan te moedigen en af te dwingen. Wat zijn de strategieën gebruikt voor het maken van degelijke documentatie voor de systemen en code van elk project, ongeacht de complexiteit ervan? Zijn er goede voorbeelden van wanneer minimale of geen documentatie nodig is?

IMHO, ik vind dat we een documentatiebeoordeling nadat een project is opgeleverd. Als het niet eenvoudig, beknopt, illustratief en gebruikersvriendelijk is, is de ontwikkelaar of technische documentatie-ingenieur de verantwoordelijkheid ervoor en moet hij het repareren. Ik verwacht ook niet dat mensen stapels documentatie maken, hoop niet dat het gebruiksvriendelijk zal zijn zoals de Head First-boeken, maar ik verwacht dat het de noodzaak voor uren aan analyse en verkwistende KT-sessies.

Is er een manier om deze waanzin te beëindigen of te verlichten? “Documentgestuurde ontwikkeling” misschien?

Opmerkingen

  • Er is nog een reden waarom er vaak geen goede documentatie is: het is erg moeilijk om goede documentatie te schrijven die niet ‘ parafraseer de code alleen in het Engels, maar beschrijft waarom de code op die manier is ontworpen / geschreven. De behoefte aan deze informatie wordt pas maanden nadat het had moeten opschrijven duidelijk.
  • Een andere serieuze reden: veel ontwikkelaars hebben Engels als tweede taal en / of schrijven Engels slecht . Je zou ze misschien kunnen dwingen om een oneliner voor een methode te schrijven, maar als je goede documentatie wilt, kun je maar beter bereid zijn ervoor te betalen en specialisten inhuren om het te doen.

Answer

Hoe code te documenteren?

Je hebt al een hint: kijk hoe Java API wordt gedocumenteerd.

Meer in het algemeen is er geen unieke set regels die voor elk project gelden. Wanneer ik aan bedrijfskritische grootschalige projecten werk, heeft de documentatie niets te maken met de documentatie die ik zou schrijven voor een kleine open source-bibliotheek, wat op zijn beurt niets te maken heeft met de documentatie van mijn persoonlijke project op middelgrote schaal. .

Waarom zijn veel open source-projecten niet goed gedocumenteerd?

Omdat de meeste open source-projecten worden gemaakt door mensen die aan die projecten bijdragen omdat het leuk is. De meeste programmeurs en ontwikkelaars beschouwen dat het schrijven van documentatie niet leuk genoeg is om gratis te doen.

Waarom veel closed-source projecten zijn niet goed gedocumenteerd?

Omdat het enorm veel geld kost om (1) goede documentatie te schrijven en (2) te onderhouden.

  1. De onmiddellijke kosten (kosten voor het schrijven van de documentatie) zijn duidelijk zichtbaar voor de belanghebbenden: als uw team vraagt om de komende twee maanden te besteden aan het documenteren van het project, moet u twee extra maanden salaris betalen.

  2. Het lo ng termijnkosten (kosten voor het onderhouden van de documentatie) worden ook vrij gemakkelijk merkbaar voor de managers, en zijn vaak het eerste doelwit wanneer ze de kosten moeten verlagen of de vertragingen moeten verkorten. Dit veroorzaakt een bijkomend probleem van verouderde documentatie die snel onbruikbaar wordt en extreem duur is om bij te werken.

  3. De besparingen op lange termijn (besparingen doordat u niet een paar dagen hoeft te verspillen aan het verkennen van de legacy-code alleen om iets fundamenteels te begrijpen dat jaren geleden had moeten worden gedocumenteerd) zijn aan de andere kant moeilijk te meten, wat het gevoel van sommige managers bevestigt dat het schrijven en bijhouden van documentatie tijdverspilling is.

Wat ik vaak zie is dat:

  1. In het begin is het team bereid om veel te documenteren.

  2. Na verloop van tijd maken de druk van deadlines en het gebrek aan interesse het steeds moeilijker om de documentatie bij te houden.

  3. Een paar maanden later kan een nieuwe persoon die zich bij het project voegt praktisch “de documentatie niet gebruiken, omdat deze helemaal niet overeenkomt met het daadwerkelijke systeem.

  4. Als we dat opmerken, geeft het management de ontwikkelaars de schuld voor het niet bijhouden van de documentatie; ontwikkelaars vragen om een paar weken te besteden aan het bijwerken ervan.

    • Als het management daarvoor een paar weken de tijd geeft, herhaalt de cyclus zich.

    • Als het management weigert, op basis van eerdere ervaring, vergroot dit alleen de slechte ervaring, aangezien het product geen documentatie heeft, maar er een paar maanden zijn besteed aan het schrijven en onderhouden ervan.

Documentatie zou een continu proces moeten zijn, net als testen. Besteed een week aan het simpelweg coderen van een paar duizenden LOC, en teruggaan naar tests en documentatie is erg, erg pijnlijk.

Hoe het team aanmoedigen om te schrijven documentatie?

Vergelijkbaar met de manieren om mensen aan te moedigen schone code te schrijven, regelmatig refactoring te doen, ontwerppatronen te gebruiken of voldoende eenheidstests toe te voegen.

  • Geef het goede voorbeeld. Als u goede documentatie schrijft, kunnen uw paren daarmee ook beginnen.

  • Voer systematische codebeoordelingen uit, inclusief formele codebeoordelingen gericht op het inspecteren van de documentatie.

  • Als sommige leden van het team bijzonder antipathisch staan tegenover goede documentatie (of überhaupt documentatie), bespreek het onderwerp dan privé met hen om te begrijpen wat de belemmeringen zijn die hen verhinderen om betere documentatie te schrijven. Als ze het gebrek aan tijd de schuld geven, zie je de oorzaak van de problemen.

  • Maak de aanwezigheid of het gebrek aan documentatie meetbaar voor een paar weken of maanden, maar doe dit niet focus daarop. U kunt bijvoorbeeld het aantal regels met opmerkingen per LOC meten, maar maak er geen permanente meting van, anders zullen ontwikkelaars lange maar zinloze opmerkingen gaan schrijven om van lage scores af te komen.

  • Gebruik gamification. Dit komt samen met het vorige punt.

  • Gebruik positieve / negatieve versterking .

  • (Zie de opmerking van SJuan76 ) Behandel het ontbreken van opmerkingen als fouten. In Visual Studio kunt u bijvoorbeeld een optie aanvinken om XML-documentatie te genereren. Als u ook controleert of alle waarschuwingen als fouten worden behandeld, zal het ontbreken van een opmerking bovenaan een klasse of methode de compilatie stoppen.

    Wat betreft de drie voorgaande punten, deze moet worden gebruikt met de nodige voorzichtigheid. Ik heb het een tijdje gebruikt met een bijzonder sterk team van beginnende programmeurs, en het eindigde met StyleCop-compliant commentaren zoals: 

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

die, hm …, niet bijzonder nuttig waren.

Onthoud: niets geautomatiseerd kan u helpen slechte opmerkingen te lokaliseren wanneer programmeurs met u willen spelen . Alleen code recensies en andere menselijke taken zullen helpen.

Zijn er goede voorbeelden van wanneer er minimale of geen documentatie nodig is?

Documentatie die de architectuur en het ontwerp uitlegt is niet nodig:

  • Voor een prototype,

  • Voor een persoonlijk project dat in een paar uur is geschreven om een taak te volbrengen, terwijl je er vrij zeker van bent dat dit project “niet langer zal worden onderhouden,

  • Voor elk project waar het duidelijk is, gezien de kleine omvang ervan, in combinatie met de bijzonder schone code, dat u meer tijd zult besteden aan het schrijven van documentatie dan alle toekomstige beheerders van de code.

In-code documentatie (codecommentaar) is volgens sommige ontwikkelaars niet nodig wanneer de code zelfdocumenterend is. Voor hen is de aanwezigheid van commentaren, behalve in de zeldzame gevallen, geen goed teken, maar een teken dat de code niet genoeg werd geherstructureerd om duidelijk te zijn zonder dat commentaar nodig is.

Ik vind dat we een documentatiebeoordeling moeten hebben nadat een project is opgeleverd.

Als uw project wordt opgeleverd, tenminste eenmaal per week is het de juiste keuze. Als uw project niet flexibel is en wordt opgeleverd met tussenpozen van zes maanden, voer dan meer regelmatige beoordelingen uit.

Opmerkingen

  • Aan ‘ hoe ‘ aan te moedigen, zou ik willen toevoegen dat veel IDEs de melding van ontbrekende documentatie als waarschuwing toestaan. Als alternatief kan misschien een statische analyse van de documentatie worden gedaan bij de OSB (dat alleen zou natuurlijk niet voldoende zijn).
  • @ SJuan76: inderdaad. Visual Studio kan het gebrek aan opmerkingen zelfs als een compileerfout beschouwen. Ik heb mijn antwoord bewerkt om daar een opmerking over toe te voegen.
  • @ArseniMourzenko – Ik las dat we wat documentatie in Agile konden aanmoedigen door verhalen voor documentatie toe te voegen. Maar deze mogen de andere verhalen niet blokkeren, d.w.z. de definitie van andere verhalen van gedaan, mag geen voltooiing van documentatieverhalen bevatten. Hoe klinkt dat?
  • @ArseniMourzenko – Ik ‘ zou graag nog twee punten aan je antwoord willen toevoegen. (1) Voeg in Jira etc. altijd een taak toe voor documentatie. (2) Laat documenten beoordelen door nog 2 mensen & en leg dat ook als een taak. Op die manier worden mensen eraan herinnerd om te documenteren & en zal het schrijven van documenten van lage kwaliteit (vanwege revisie) vermijden. Als u ‘ geen prioriteit geeft aan & bekijk het, dan wordt het slecht. Ik weet dat Amazon veel documenten & doc-recensies doet, misschien een beetje te veel.

Antwoord

Ik denk dat je een onderscheid moet maken tussen commentaar en documentatie. Hoewel commentaren beschrijvend zijn, missen ze consistentie, ze zijn verspreid over de hele code. Commentaar mag nooit code compenseren die zichzelf niet genoeg beschrijft, in plaats daarvan zou het andere programmeurs op lastige onderdelen moeten wijzen.

Of code gedocumenteerd moet worden, hangt af van de schaal van het project. Er zijn vast en zeker mensen die geloven dat alles gedocumenteerd moet worden, en het lijkt gemakkelijk om die gedachte te rechtvaardigen, want wie zou zich durven verzetten kennis documenteren? Gelukkig is softwareontwikkeling geen wetenschap, en de wereld stort niet in als de details achter je kleine programma onduidelijk worden. Het betreft nu professionele software voor gebruik door veel ontwikkelaars, ja, natuurlijk moet je je code documenteren. Maar als je in de positie bent om op dat niveau te coderen, dan zou je dat duidelijk weten.

tl; dr

Als je “vraagt dat elk project goed wordt gedocumenteerd, dan vraag je teveel .

Reacties

  • Fortunately software development is not science Vertel me alsjeblieft meer over waarom je dit gelooft.
  • @Borat – Softwareontwikkeling is een technische discipline, wat inhoudt dat het de tools gebruikt die door de wetenschap worden geboden.
  • Ik vraag niet dat alles wordt gedocumenteerd. Het zou moeten worden net genoeg om een algemeen overzicht te geven van wat een systeem en code doet. Bijvoorbeeld. Vertel me alsjeblieft hoe ik mijn tv moet gebruiken. Het kan me ‘ niet schelen of het LCD, CRT, Vacuümbuizen of solid-state apparaten om de klus te klarenAls een reparateur die info wil, maak dan aparte documentatie voor hem.
  • Als je een overzicht op hoog niveau wilt, zijn identificatienamen voldoende. Net zoals de knop op uw tv een ” Aan ” label kan hebben. Dus je vraagt om details op laag niveau.
  • @LeopoldAsperger: ik denk dat Borat het heeft over het documenteren van architectuur en ontwerp, niet over methoden in klassen.

Geef een reactie

Het e-mailadres wordt niet gepubliceerd. Vereiste velden zijn gemarkeerd met *