R Language
Meta: Documentatierichtlijnen

Opmerkingen

Goede voorbeelden maken

De meeste richtlijnen voor het maken van goede voorbeelden voor Q&A worden overgenomen in de documentatie.

• Maak het minimaal en kom ter zake. Complicaties en uitweidingen zijn contraproductief.

• Gebruik zowel werkende code als proza om het uit te leggen. Geen van beide is op zichzelf voldoende.

• Vertrouw niet op externe bronnen voor gegevens. Genereer gegevens of gebruik indien mogelijk de datasetsbibliotheek:

  library(help = "datasets")
  

Er zijn enkele aanvullende overwegingen in de context van Documenten:

• Raadpleeg waar van toepassing ingebouwde documenten zoals ?data.frame . De SO-documenten zijn geen poging om de ingebouwde documenten te vervangen. Het is belangrijk om ervoor te zorgen dat nieuwe R-gebruikers weten dat de ingebouwde documenten bestaan en hoe ze te vinden.

• Verplaats inhoud die van toepassing is op meerdere voorbeelden naar de sectie Opmerkingen.

Stijl

aanwijzingen

Als u wilt dat uw code kopieerbaar is, verwijdert u aanwijzingen zoals R> , > of + aan het begin van elke nieuwe regel. Sommige auteurs van Documenten maken het kopiëren en plakken niet gemakkelijk, en dat is prima.

Console-uitgang

Console-uitvoer moet duidelijk worden onderscheiden van code. Gemeenschappelijke benaderingen zijn onder meer:

• Neem prompts op bij invoer (zoals te zien bij gebruik van de console).
• Geef commentaar op alle uitvoer, waarbij # of ## elke regel begint.
• Druk af zoals het is, vertrouwend op de leidende [1] om de uitvoer te laten opvallen ten opzichte van de invoer.
• Voeg een lege regel toe tussen code en console-uitvoer.

toewijzing

= en <- zijn prima voor het toewijzen van R-objecten. Gebruik witruimte op de juiste manier om te voorkomen dat er moeilijk te analyseren code wordt geschreven, zoals x<-1 (dubbelzinnig tussen x <- 1 en x < -1 )

Code opmerkingen

Leg het doel en de functie van de code zelf uit. Er is geen harde regel of deze verklaring in proza of in codereacties moet zijn. Proza is misschien beter leesbaar en zorgt voor langere uitleg, maar code-opmerkingen maken het kopiëren eenvoudiger. Houd beide opties in gedachten.

secties

Veel voorbeelden zijn kort genoeg om geen secties nodig te hebben, maar als u ze gebruikt, begint u met H1 .