de waarde van Codedocumentatie

Codedocumentatie is het verzamelen van gemakkelijk te begrijpen afbeeldingen en geschreven beschrijvingen die uitleggen wat een codebase doet en hoe het kan worden gebruikt.

het kan eenvoudige verklarende opmerkingen boven functies en blokken zijn, of een volledig ontwikkelaarshandboek, compleet met prescriptieve stijl dos-and-don ‘ ts, overzichten van elk deel van de applicatie, en benaderingen van de meest voorkomende soorten coderingstaken.

het is vaak het beste om een gelukkig medium te vinden tussen deze twee uitersten wanneer u de bewuste beslissing neemt om uw code te becommentariëren en de gnarlier gebieden van een codebase in Gewone Taal te schetsen.

Waarom uw code documenteren?

waarom de moeite nemen om over uw code te schrijven, in plaats van alleen code te schrijven? Zou dat niet productiever zijn?

mentale opslagpunten

documentatie is als een mentaal opslagpunt voor die momenten waarop je eindelijk krijgt wat er aan de hand is aan het einde van de dag en je momentum niet wilt verliezen. Goed gedocumenteerde code zal ervoor zorgen dat wanneer je nodig hebt om terug te duiken in morgenochtend (of enkele maanden vanaf nu), je niet zo veel tijd nemen om op snelheid te komen.

gedocumenteerde code wordt hergebruikt

het verschil tussen een Gebruikte bibliotheek en een ongebruikte bibliotheek komt vaak neer op de documentatie.

wie wil een opensourcebibliotheek zonder papieren gebruiken of bijdragen aan een project zonder papieren? Bijna niemand.

in de meeste gevallen gebruikt u liever een minder krachtige bibliotheek met documenten. Waarom? Omdat de documentatie andere punten van informatie over een codebase overbrengt. De ontwikkelaars geloven dat het project de tijd en energie waard is om er in eenvoudige taal over te schrijven, zodat iedereen die geïnteresseerd zou kunnen zijn snel aan de slag kan en leert hoe het werkt, en waarom belangrijke beslissingen werden genomen.

het vinden van een nieuw, interessant en goed gedocumenteerd project in uw favoriete taal kan erg spannend en leuk zijn. Laten we eens kijken naar het extreme alternatief: een ongedocumenteerde codebibliotheek gebruiken en mogelijk bijdragen aan een schijnbaar Byzantijnse codebase… het klinkt behoorlijk pijnlijk, toch?

waarom hebt u uw eigen code niet gedocumenteerd?

documentering code maakt deel uit van het schrijven van goede code

een hoeksteen van goede code is onderhoudbaarheid, bereikt door middel van begrijpelijke, leesbare documentatie.

er zijn meerdere manieren om code te documenteren:

• goede namen kiezen voor variabelen en functies
• korte opmerkingen achterlaten in de code om toekomstige lezers context te geven
• illustratieve afbeeldingen toevoegen, zoals sequentiediagrammen en entiteitrelatiediagrammen
• API-documenten leveren, elke klasse, methode, argument en retourwaarde beschrijven
• gebruikmakend van een statisch getypte taal, zoals TypeScript (typen als documentatie))

Vergelijk twee voorbeelden

stel dat je wat gegevens krijgt van een backend API en het “ingressing” – het omzetten in een meer bruikbare vorm voor een front-end UI. Hier is de eerste van twee mogelijke oplossingen.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

de bovenstaande code kan pijnlijk zijn. Aan de naam kun je zien dat dit een soort converter is die w als param gebruikt.

het lijkt erop dat het een header, misschien details, en iets genaamd revs retourneert. Waar komt revs eigenlijk vandaan? Natuurlijk zijn er geen details over de inkomende variabele namen note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… of toch wel? Is rr de afkorting van returned rev? Wie zal het zeggen.

laten we eens kijken naar het tweede voorbeeld.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

Wow, wat anders! Deze functie zit in een util bestand, dus het hoofdbestand is al minder rommelig. Het is ook geschreven in TypeScript in plaats van gewoon JavaScript, dus we hebben het voordeel van typedefinities om ons te helpen begeleiden.

we converteren widgetRespDTOs naar widget s. hoewel afgekort, hebben we volledige kennis van wat wResp is. We maken een widgetHeader, en een widgetDetail, dat is gemakkelijk te zien. We begrijpen ook wat oTS en cTS zijn. We kunnen zien dat WidgetRevisionsRespDTOs in WidgetRespDTOgenest zijn.

iemand is heel vriendelijk omgedoopt tot de inkomende variabelen zodat iedereen die deze code ziet weet wat ze zijn. Tot slot zien we dat een Widget moet bestaan uit het geretourneerde {widgetHeader, widgetDetail, widgetRevisions} object, omdat het moet overeenkomen met het retourtype Widget dat bovenaan is opgegeven.

welke code zou u zich beter voelen bij het gebruik?

wie profiteert?

goed gedocumenteerde code komt veel mensen ten goede:

Junior ontwikkelaars

omdat het in eenvoudige taal en gemakkelijk te begrijpen is, helpt documentatie jonge ontwikkelaars en nieuwe teamleden zich zeker te voelen wanneer ze in een codebase springen. Dit voorkomt frustratie en vroegtijdige stopzetting van een taak omdat het te ingewikkeld en te snel wordt.

het is ook handig voor junior ontwikkelaars om hun eigen documentatie te schrijven, zodat ze hun code met anderen kunnen delen en zodat ze hun code beter kunnen begrijpen.

Senior ontwikkelaars

door de tijd te nemen om nu te documenteren, besteden senior ontwikkelaars minder tijd aan het uitleggen van hun code aan anderen in de toekomst.

ze kunnen ook complexere code schrijven. Gewone taaldocumentatie laat anderen het gebruiken als een zwarte doos, zonder de innerlijke werking te begrijpen.

Teams & open source projecten

personeelswijzigingen kunnen een enorme vertraging van een project veroorzaken. Up-to-date en goed gedocumenteerde code kan dienen als verzekering tegen dergelijke vertragingen en laat de resterende teamleden om een stap terug te nemen, de code van een hoog niveau te herzien en te beslissen over de beste manier van handelen vooruit, en indien nodig, aan boord van nieuwe medewerkers.

u

wanneer u een code documenteert, moet u deze samenvatten. Om goed samen te vatten, moet je in staat zijn om het te begrijpen, met de verschillende delen in je hoofd op hetzelfde moment. Schrijven of bijdragen aan de documentatie is een snelkoppeling naar echt begrip van een codebase, het maken van enorme bijdragen, en het gevoel dat een groot deel van een geweldig team.

goede documentatie kan onze coderingservaring opdrogen

als programmeur heb je waarschijnlijk al gehoord van het ‘ Don ’t Repeat Yourself’ – principe als sleutel tot het schrijven van schone en beknopte code. In plaats van het herhalen van hetzelfde codeblok meerdere keren, Schrijf een functie die kan worden geschreven en gebruikt over uw toepassing.

op dezelfde manier zouden u en uw team geen soortgelijke problemen moeten tegenkomen en vervolgens het wiel opnieuw moeten uitvinden elke keer dat u probeert ze op te lossen. Bijvoorbeeld, heb je ooit gehoord van een van uw collega ‘ s of vond jezelf zeggen:

“Agh, ik loste iets zeer vergelijkbaar met dit, maar ik weet nooit meer hoe ik het doen als het komt… Ik moet het waarschijnlijk ergens opschrijven, hè?”

dan zie je dat je dezelfde stack Overflow threads steeds opnieuw scant.

Red uzelf en uw collega ‘ s van dit verdriet door de geest van het droge Principe te volgen en een document te schrijven dat u kunt gebruiken telkens wanneer het probleem zich voordoet! Dit zal u en anderen in uw team helpen tijd te besparen en effectiever te zijn in het schrijven van eenvoudiger, beter beheersbaar en efficiënter code.

wat heeft codedocumentatie, of het ontbreken daarvan, voor u gevolgen?