R Language
Meta: Pautas de documentación.

Observaciones

Haciendo buenos ejemplos

La mayoría de las guías para crear buenos ejemplos de preguntas y respuestas se trasladan a la documentación.

• Hazlo mínimo y llega al punto. Las complicaciones y digresiones son contraproducentes.

• Incluya tanto el código de trabajo como la prosa explicándolo. Ninguno de los dos es suficiente por sí solo.

• No confíe en fuentes externas para obtener datos. Genere datos o use la biblioteca de conjuntos de datos si es posible:

  library(help = "datasets")
  

Hay algunas consideraciones adicionales en el contexto de Docs:

• Consulte los documentos incorporados como ?data.frame cuando sea relevante. Los documentos SO no son un intento de reemplazar los documentos incorporados. Es importante asegurarse de que los nuevos usuarios de R sepan que los documentos incorporados existen y cómo encontrarlos.

• Mueva el contenido que se aplica a varios ejemplos a la sección Comentarios.

Estilo

Indicaciones

Si desea que su código se pueda copiar y pegar, elimine las indicaciones como R> , > o + al comienzo de cada nueva línea. Algunos autores de Docs prefieren no facilitar copiar y pegar, y eso está bien.

Salida de consola

La salida de la consola debe distinguirse claramente del código. Los enfoques comunes incluyen:

• Incluya indicaciones en la entrada (como se ve cuando se usa la consola).
• Comente todas las salidas, con # o ## comenzando cada línea.
• Imprima como está, confiando en el [1] inicial para que la salida se destaque de la entrada.
• Agregue una línea en blanco entre el código y la salida de la consola.

Asignación

= y <- están bien para asignar objetos R Use el espacio en blanco adecuadamente para evitar escribir código que sea difícil de analizar, como x<-1 (ambiguo entre x <- 1 y x < -1 )

Comentarios del código

Asegúrese de explicar el propósito y la función del código en sí. No hay una regla estricta sobre si esta explicación debe estar en prosa o en comentarios de código. La prosa puede ser más legible y permite explicaciones más largas, pero los comentarios de código facilitan el pegado y copiado. Tenga ambas opciones en mente.

Secciones

Muchos ejemplos son lo suficientemente cortos como para no necesitar secciones, pero si los usa, comience con H1 .