R Language
Meta: linee guida per la documentazione

Osservazioni

Fare buoni esempi

La maggior parte delle linee guida per la creazione di buoni esempi di domande e risposte continua nella documentazione.

• Rendilo minimo e raggiungi il punto. Complicazioni e divagazioni sono controproducenti.

• Includere sia il codice che il prose che lo spiegano. Nessuno dei due è sufficiente da solo.

• Non fare affidamento su fonti esterne per i dati. Genera dati o utilizza la libreria di set di dati, se possibile:

  library(help = "datasets")
  

Ci sono alcune considerazioni aggiuntive nel contesto di Documenti:

• Fare riferimento a documenti incorporati come ?data.frame ogni ?data.frame sia pertinente. I documenti SO non sono un tentativo di sostituire i documenti incorporati. È importante assicurarsi che i nuovi utenti R sappiano che esistono i documenti incorporati e come trovarli.

• Sposta il contenuto che si applica a più esempi alla sezione Note.

Stile

prompt

Se vuoi che il tuo codice sia passibile di una copia, rimuovi prompt come R> , > o + all'inizio di ogni nuova riga. Alcuni autori di Doc preferiscono non semplificare il copia-incolla, e va bene così.

Uscita della console

L'output della console dovrebbe essere chiaramente distinto dal codice. Gli approcci comuni includono:

• Include prompt su input (come si vede quando si usa la console).
• Commenta tutti gli output, con # o ## iniziando ogni riga.
• Stampa così com'è, affidandosi al leader [1] per far risaltare l'output dall'input.
• Aggiungi una riga vuota tra il codice e l'output della console.

assegnazione

= e <- vanno bene per l'assegnazione di oggetti R. Usa lo spazio bianco in modo appropriato per evitare di scrivere codice difficile da analizzare, come x<-1 (ambiguo tra x <- 1 e x < -1 )

Codice commenti

Assicurati di spiegare lo scopo e la funzione del codice stesso. Non esiste una regola rigida sul fatto che questa spiegazione debba essere in prosa o nei commenti al codice. La prosa può essere più leggibile e consente spiegazioni più lunghe, ma i commenti del codice facilitano il copia-incolla. Tieni a mente entrambe le opzioni.

sezioni

Molti esempi sono abbastanza brevi da non aver bisogno di sezioni, ma se li usi, inizia con H1 .