Code Documentation: The Complete Beginner’ s Guide
u bent een klein eindje in uw eerste programmeertaak, en het wordt makkelijker. In het begin, alle code die je moest omgaan met zou kunnen overweldigd en verward je, maar je begint het onder de knie te krijgen. Dat is geweldig! Nu vraag je je af hoe je de code die je schrijft naar het volgende niveau kunt brengen. Hoewel er veel dingen te leren over je programmeerstack, waarvan vele je een betere programmeur zullen maken, zijn er een paar die je zullen dienen, ongeacht in welke stack je werkt. Een daarvan is code documentatie.
veel ontwikkelaars schrijven niet genoeg documentatie, omdat ze de waarde niet zien of omdat ze het gevoel hebben dat ze geen tijd hebben. Je hoeft niet zo ‘ n ontwikkelaar te zijn. Met een beetje tijd en veel oefening, kunt u documentatie toevoegen voor uw code die het lezen ervan een plezier maakt om te gebruiken voor zowel u als iedereen die langs komt.
goede documentatie komt in vele vormen
wanneer de meeste ontwikkelaars denken aan code documentatie, denken ze aan commentaren. Opmerkingen kunnen waardevolle toevoegingen aan code zijn, maar ze zijn niet de enige definitie van documentatie. Documentatie is alles wat je naast je code schrijft om iemand anders te helpen begrijpen hoe het werkt. Je denkt er misschien niet zo over, maar een goed voorbeeld van code documentatie is een README bestand. Een goed voorbeeld van basisdocumentatie is de Express.js README bestand. Het beantwoordt een aantal belangrijke vragen over het framework en vertelt u hoe u het in uw project kunt opnemen, hoe u het kunt installeren en hoe u tests kunt uitvoeren.
goede documentatie kan ook in de vorm van API-documentatie komen. Nogmaals, Express.js is een goed voorbeeld. Deze versie van documentatie is meer een referentiebibliotheek voor ontwikkelaars die het framework gebruiken. U vindt antwoorden op vragen over wat individuele functies doen en wat verschillende parameters voor die functies betekenen. Zonder die kwaliteitsdocumentatie, zou Express niet zo veel teams gebruiken als ze doen.
en natuurlijk kunt u ook in-line opmerkingen gebruiken om code te documenteren. Dit soort opmerkingen worden meestal niet gebruikt om mensen buiten je eigen team te leren over de code. In plaats daarvan zijn ze nuttig om uit te leggen wat er gebeurt in een bepaald stukje code aan je teamgenoten of aan je toekomstige zelf.
waarom u uw Code
moet documenteren zoals hierboven is opgemerkt, begrijpen veel ontwikkelaars het doel van code-documentatie niet. Ze zullen beargumenteren dat goede code zelfdocumenterend moet zijn en dat je het niet hoeft uit te leggen. Deze mensen zijn, in één woord, verkeerd. De waarheid is dat goede documentatie een essentieel onderdeel is van elke code base. Waarom? Omdat mensen niet al je code hoeven te lezen om te begrijpen wat het doet. “Mensen” in die vorige zin kan verwijzen naar iedereen, inclusief je toekomstige zelf.
de waarheid is dat vaak de” mensen ” die code moeten begrijpen nadat het geschreven is, Jij bent. Dat kleine beetje logica dat zo slim leek toen je het zes maanden geleden schreef, is vandaag misschien moeilijk te begrijpen. Als uw code goed gedocumenteerd is, hoeft u geen tijd te besteden aan het proberen te begrijpen wat het doet. Je zult in staat zijn om een paar seconden te kijken naar de beschrijving en dan terug te gaan naar waar je nu aan werkt.
als je het geluk hebt om te werken aan code die door tientallen of honderden ontwikkelaars wordt gebruikt, is goede documentatie nog belangrijker. Het leven van uw gebruikers zal aanzienlijk worden verbeterd door uw tijd besteed aan het schrijven van goede documentatie, en ze zullen u bedanken voor. Letterlijk!
de sleutel om te onthouden is dat goede documentatie meer tijd bespaart dan nodig is om het te schrijven. Het kan jouw tijd zijn, of het kan de tijd zijn van teamleden, of zelfs mensen die je nooit zult ontmoeten. Soms zal het schrijven van documentatie je zelfs helpen een deel van je code te herkennen dat te ingewikkeld is, zodat je het kunt vereenvoudigen.
enkele veelvoorkomende Documentatiefouten
als junior Ontwikkelaar zult u tijd moeten besteden aan het leren wat documentatie effectief maakt. Het goede nieuws is dat je kunt leren van mensen die voor je zijn gegaan, zodat je veelvoorkomende fouten kunt vermijden.
onder-documentatie
een veel voorkomende fout die ik zie bij codedocumentatie is het documenteren van informatie die al duidelijk zichtbaar is. Bijvoorbeeld, lazy ontwikkelaars zullen “documentatie” toe te voegen aan een functie door het toevoegen van een blok dat de naam van een functie, evenals de namen van elke parameter en hun individuele types biedt. Dit soort documentatie is nutteloos! Het duurt seconden voor iemand om de naam van de functie en de parameters die het duurt te lezen. Dat is geen documentatie, het is gewoon herhaling. In plaats daarvan moet de documentatie een snel beetje informatie bevatten over wat de functie doet en hoe elke parameter het gedrag van de functie verandert of waarom het nodig is.
Overdocumentatie
het tegenovergestelde patroon kan ook een ernstig probleem zijn. Om te voorkomen dat er te weinig documentatie wordt geschreven, schrijven sommige ontwikkelaars graag de verklaring uit voor elk klein beetje logica dat in een functie zit. Ze documenteren nauwgezet elke redenering die ging in het creëren van de functie. Tegen de tijd dat ze klaar zijn, kunnen ze net zo lang bezig zijn met het schrijven van de functie als met het schrijven van de documentatie. Wat erger is, de documentatie is vaak moeilijk te begrijpen en duurt net zo lang als het lezen van de code. Dat soort documentatie is ook een verspilling van tijd. In plaats daarvan geeft goede documentatie een fundamentele uitleg van zowel het wat als het waarom. Als er bijzonder lastige delen van de code te begrijpen zijn, dan moet documentatie alleen die delen uitleggen.
vertrouwend op Tests om
af en toe, kom je iemand tegen die beweert dat de beste vorm van documentatie unit tests zijn. Die aanpak heeft een grote tekortkoming: het lezen van unit tests is vaak net zo moeilijk om te doen als het lezen van code zelf. Elke ontwikkelaar die wil leren wat uw code doet zal een grote eerste stap hebben, terwijl ze jagen en lees al uw unit tests. Velen zullen gewoon opgeven voordat ze bereiken wat ze van plan waren te doen. Hoewel unit testing een waardevolle aanvulling is op elke codebasis, is het geen vervanging voor goede documentatie.
manieren om documentatie naar het volgende niveau te brengen
als u op een grote codebasis werkt, kan codedocumentatie ontmoedigend aanvoelen, vooral als u tot nu toe niet ijverig bent geweest met het documenteren van code. Het voelt alsof je de Oceaan probeert te koken. Als je een grote codebasis hebt, of een waarvan je weet dat goede documentatie van cruciaal belang is, wil je misschien geautomatiseerde codedocumentatietools onderzoeken. Deze tools vereenvoudigen drastisch het proces van het schrijven van consistente, goede documentatie voor een heel team. Een tool als GhostDoc zal op intelligente wijze naar je code kijken en sjablonen gebruiken die door je team zijn opgesteld om je Documentatie te starten met een paar toetsaanslagen. Geautomatiseerde documentatietools verwijderen een van de andere veel voorkomende redenen om zich te verzetten tegen het schrijven van documentatie: het kost te veel tijd.
zodra u consistente documentatie hebt, kunt u met andere hulpmiddelen die documentatie eenvoudig delen. Geautomatiseerde documentatietools nemen de pijn weg van het ontwikkelen van goede documentatie voor zaken als openbare API ‘ s die uw code biedt.
vandaag beginnen
het schrijven van goede documentatie is een stuk eenvoudiger dan het schrijven van code. In tegenstelling tot code, documentatie is niet een alles-of-niets onderneming. Begin met een doel om elke dag goede documentatie te schrijven voor één functie. Dat soort praktijk bouwt gezonde gewoonten, en je zult de uitbetaling op de weg te zien als je veel minder tijd besteden aan het proberen om delen van uw code base te begrijpen. Na verloop van tijd zal het verkeerd gaan voelen als je code schrijft die geen goede documentatie heeft. Tijdens het controleren van de code ga je wijzen op manieren om documentatie te verbeteren aan je collega ‘ s. Een kleine gewoonte zal de code van uw team voor uw hele bedrijf te verbeteren.
leer hoe GhostDoc kan helpen om uw XML-opmerkingen te vereenvoudigen, de documentatie van de Help-kwaliteit te produceren en te onderhouden.
Over de auteur
Eric Boersma
Eric Boersma is een software ontwikkelaar en development manager die alles al gedaan, van IT-beveiliging in de farmaceutische sector te schrijven intelligence-software voor de AMERIKAANSE regering om te bouwen voor de internationale ontwikkeling van teams voor non-profitorganisaties. Hij houdt ervan om te praten over de dingen die hij heeft geleerd langs de weg, en hij geniet van het luisteren naar en leren van anderen ook.
