Development

Software-ontwikkeling
code cleaner

Google vertelt hoe je documentatie schrijft

Google geeft een stijlboek uit om ontwikkelaars op te voeden

© CC0 - Pixabay
8 september 2017

Google geeft een stijlboek uit om ontwikkelaars op te voeden

De stijlgids die Google publiceerde, is dezelfde als die intern gebruikt wordt door ontwikkelaars om goede documentatie bij code te schrijven.

Slechtgeschreven of het ontbreken van documentatie is mogelijk nog problematischer dan slecht geschreven code, zeker in de open source gemeenschap. Nieuwe deelnemers aan een project moeten eerst veel moeite steken in het begrijpen van de bijdragen van anderen aan de code. Dat bevordert het dupliceren van functies.

In de stijlgids is veel aandacht voor het netjes documenteren van API code en voor command-line syntax.

De stijlgids is er een uitgebreide sectie met een woordenlijst zodat iedere ontwikkelaar dezelfde omschrijving en spelling gebruikt. Wanneer heb je het over "app" en wanneer over "application". Ook is er aandacht voor de 'tone of voice' Ook is er aandacht voor het gebruik van aanhalingstekens. De makers wijzen er op dat de stijlgids een levend document is en dus in de tijd wordt aangepast aan nieuwe routines.

Google is niet de eerste die een stijlgids heeft uitgebracht. Atlassian - producent van bekende workflowsoftware als Jira - heeft er een en ook WordPress. Maar de Google stijlgids gaat veel verder de diepte in.

Lees meer over
Lees meer over Development OP AG Intelligence
Reactie toevoegen
De inhoud van dit veld is privé en zal niet openbaar worden gemaakt.