R Language
Meta: Guide de documentation

Remarques

Faire de bons exemples

La plupart des conseils pour créer de bons exemples de questions-réponses sont repris dans la documentation.

• Rendez-le minimal et allez droit au but. Les complications et les digressions sont contre-productives.

• Inclure à la fois le code de travail et la prose l'expliquant. Ni l'un ni l'autre ne suffit à lui seul.

• Ne comptez pas sur des sources externes pour les données. Générer des données ou utiliser la bibliothèque de jeux de données si possible:

  library(help = "datasets")
  

Il y a quelques considérations supplémentaires dans le contexte de Docs:

• Reportez-vous à la documentation ?data.frame comme ?data.frame lorsque ?data.frame est pertinent. Les documents SO ne sont pas une tentative de remplacement des documents intégrés. Il est important de s’assurer que les nouveaux utilisateurs R savent que les documents intégrés existent ainsi que la manière de les trouver.

• Déplacer le contenu qui s'applique à plusieurs exemples vers la section Remarques.

Style

Instructions

Si vous souhaitez que votre code soit copiable, supprimez les invites telles que R> , > ou + au début de chaque nouvelle ligne. Certains auteurs Docs préfèrent ne pas faciliter le copier-coller, et ce n'est pas grave.

Sortie de la console

La sortie de la console doit être clairement distinguée du code. Les approches communes incluent:

• Inclure les invites à l'entrée (comme vu lors de l'utilisation de la console).
• Commentez toutes les sorties, avec # ou ## commençant chaque ligne.
• Imprimer tel quel, en faisant confiance au premier [1] pour que la sortie se démarque de l’entrée.
• Ajoutez une ligne vide entre le code et la sortie de la console.

Affectation

= et <- sont bons pour assigner des objets R. Utilisez des espaces blancs de manière appropriée pour éviter d'écrire du code difficile à analyser, tel que x<-1 (ambigu entre x <- 1 et x < -1 )

Commentaires de code

Assurez-vous d'expliquer le but et la fonction du code lui-même. Il n'y a pas de règle stricte pour savoir si cette explication doit être en prose ou en code. La prose peut être plus lisible et permet des explications plus longues, mais les commentaires de code facilitent le copier-coller. Gardez les deux options à l'esprit.

Sections

De nombreux exemples sont suffisamment courts pour ne pas nécessiter de sections, mais si vous les utilisez, commencez par H1 .