R Language
Meta: Riktlinjer för dokumentation

Anmärkningar

Gör goda exempel

De flesta av riktlinjerna för att skapa bra exempel på frågor och svar överförs till dokumentationen.

• Gör den minimal och komma till punkten. Komplikationer och avtryckningar är kontraproduktiva.

• Inkludera både arbetskod och prosa som förklarar det. Ingen av dem räcker på egen hand.

• Lita inte på externa källor för data. Generera data eller använd datasättbiblioteket om möjligt:

  library(help = "datasets")
  

Det finns några ytterligare överväganden i samband med Dokument:

• Se inbyggda dokument som ?data.frame när det är relevant. SO-dokumenten är inte ett försök att ersätta de inbyggda dokumenten. Det är viktigt att se till att nya R-användare vet att de inbyggda dokumenten finns och hur man hittar dem.

• Flytta innehåll som gäller flera exempel till avsnittet Kommentarer.

Stil

Frågar

Om du vill att din kod ska vara kopierbar kan du ta bort instruktioner som R> , > eller + i början av varje ny rad. Vissa dokument författare föredrar att inte göra kopiera klistra in lätt, och det är okej.

Konsolutgång

Konsolutgång bör tydligt skiljas från kod. Vanliga metoder inkluderar:

• Inkludera meddelanden på ingången (sett när du använder konsolen).
• Kommentera all utgång, med # eller ## startar varje rad.
• Skriv ut som den är, och litar på den ledande [1] att göra att utskotten sticker ut från ingången.
• Lägg till en tom rad mellan kod och konsolutgång.

Uppdrag

= och <- är bra för att tilldela R-objekt. Använd vitt utrymme på lämpligt sätt för att undvika att skriva kod som är svår att analysera, till exempel x<-1 (tvetydigt mellan x <- 1 och x < -1 )

Kod kommentarer

Var noga med att förklara syftet och funktionen för själva koden. Det finns ingen hård och snabb regel om denna förklaring ska vara i prosa eller i kodkommentarer. Prosa kan vara mer läsbar och möjliggör längre förklaringar, men kodkommentarer gör det lättare att klistra in kopior. Tänk på båda alternativen.

sektioner

Många exempel är tillräckligt korta för att inte behöva avsnitt, men om du använder dem börjar du med H1 .