Hopp-start-kodekommentarer med GhostDoc

Når du jobber med eksisterende applikasjonskode, er sjansen for å finne den koden grundig dokumentert liten. De fleste utviklere er ikke for krevende - vi trenger bare en grunnleggende forståelse av hva en applikasjon skal gjøre når de blir konfrontert med en metode (til og med en rask setning om hva den gjør og informasjon om dens parametere) og borte. Visual Studio-tillegg GhostDoc gir rammen for kodekommentarer med et museklikk eller tastetrykk.

GhostDoc fungerer som annonsert

Jeg var bekymret for løftet fra GhostDoc. En kollega hadde bedt meg i ganske lang tid for å bruke det, men jeg forble resolutt (sta?) Og stakk fast med min gamle måte å gjøre ting på (for hånd). Jeg ble bedt om å jobbe med en eksisterende kodebase og sette inn kommentarer som en guide for andre utviklere, så jeg til slutt ga etter og installerte GhostDoc for (forhåpentligvis) å forenkle oppgaven. Nå er jeg fan av verktøyet.

GhostDoc-nedlastingen kommer i to smaker: Basic og Pro. GhostDoc Basic er gratis og gir den grunnleggende funksjonaliteten til verktøyet, ettersom du enkelt kan sette inn kommentarer i koden din med noen få klikk. GhostDoc Pro legger til noen flere funksjoner som å kommentere en komplett fil med ett klikk og automatiserte kommentarblokker er konfigurerbare. GhostDoc Pro brukes i skjermdumpene i dette innlegget, men funksjonene dekket er tilgjengelige i begge versjoner.

Til fingerspissene

Når den er installert, er GhostDoc tilgjengelig via rullegardinmenyen Verktøy i Visual Studio IDE. Figur A viser menyen slik den vises med GhostDoc Pro installert. GhostDoc Basic oppretter den samme menyen med noen få mindre alternativer som Document File nedtonet, slik at den ikke er tilgjengelig. I tillegg er en grunnleggende GhostDoc-kontekstmeny tilgjengelig ved å høyreklikke på musen når du er i kildekoden. Dette lar deg dokumentere under koding - forestill deg det! Figur A
GhostDoc-menyen i Visual Studio 2010

Min favoritt tilnærming til å kommentere er via en forhåndsdefinert snarvei som er konfigurert under installasjonen. Ctrl Shift D -kombinasjonen er standard, men du kan velge hva du vil innen grunn, fordi Ctrl Shift Delete ikke er tilgjengelig av åpenbare grunner. Hvis du bestemmer deg for at du ikke liker den valgte tastekombinasjonen, kan du endre den via GhostDoc-menyen via Valg om tilordne snarvei som vist i figur A. Du kan også "Kjør konfigurasjonsveiviseren" for å kjøre konfigurasjonsveiviseren som kjøres først installert.

Sette inn kommentarer

En individuell del av koden (metode, egenskap, klassedefinisjon osv.) Kan kommenteres ved å flytte markøren til sin beliggenhet innenfor kildekoden og velge Dokument dette eller ved å bruke tastekombinasjonen. Som et eksempel kommenterte jeg en eksisterende metode i koden min som neste utdrag viser:

 /// 

/// Populerer teambarneknuter.

///

/// Nåværende node.

///

///

public static System.Windows.Forms.TreeNode populateTeamChildNodes (System.Windows.Forms.TreeNode curNode)

Kommentaren viser at den kjente igjen parametrene og at den returnerer en verdi. I tillegg gjorde det en tapper innsats å plassere tekst i sammendragselementet ved å behandle metodenavnet - parsing av ordene og legge til "the so so befolkeTeamChildNodes blir" Populerer teambarneknuter. " Å gjøre det samme med en klassedeklarasjon gir lignende resultater:

 /// 

/// Sammendragsbeskrivelse for klasse1.

///

///

offentlig klasse Class1

Det er ikke prangende, men det er poenget med GhostDoc - det skriver bare XML-kommentarer. Du kan gå gjennom koden og sette inn disse kommentarene enkeltvis eller kommentere en fullstendig fil mens du er på farten (bare i Pro-versjonen), men du må fortsatt oppdatere kommentarene.

Merk: Kommentarene generert av GhostDoc er ikke nyttige før du legger til tekst i kommentarene og andre relevante detaljer. Dermed løser GhostDoc faktisk ikke noe - det gir deg et rammeverk for å legge inn nyttig informasjon i kommentarer.

Ønskeliste

GhostDoc er ikke for alle; verktøyet gjør en grunnleggende oppgave, og det fokuserer på det uten å legge til mange andre funksjoner. En vanlig klage er mangelen på støtte for å generere en XML-fil eller til og med HTML fra kommentarene, men du kan bruke et verktøy som Doxygen til å lage HTML-output. Jeg vil at GhostDoc legger til returtypen i kommentarelementet for retur, samt en liste over unntak som er reist i kommentarblokken.

Hvis det er noe du virkelig ønsker eller trenger, kan du legge ut en kommentar til GhostDoc-diskusjonsforum, ettersom de ser ut til å være veldig responsive.

Legg igjen en sti

Kommentering av kildekode har vært et problem siden utviklere begynte å bygge applikasjoner. Heldigvis gjør GhostDoc å lage nyttige kommentarer like enkle som noen få knapp eller museklikk.

Det er mange gode Visual Studio-tillegg i dag for dokumentasjon, samt mange flere oppgaver. Hvilke verktøy foretrekker du i den daglige kodingen? Del dine anbefalinger og tanker med TechRepublic-samfunnet.

© Copyright 2021 | pepebotifarra.com