R Language
Meta: Руководство по документации

замечания

Хорошие примеры

Большинство рекомендаций по созданию хороших примеров для вопросов и ответов переносятся в документацию.

• Сделайте его минимальным и дойдете до сути. Осложнения и отступления являются контрпродуктивными.

• Включите как рабочий код, так и прозу, объясняющие его. Ни один из них не является достаточным.

• Не полагайтесь на внешние источники данных. Создайте данные или используйте библиотеку наборов данных, если это возможно:

  library(help = "datasets")
  

В контексте Документов есть несколько дополнительных соображений:

• Обратитесь к встроенным документам типа ?data.frame если это необходимо. SO Docs не являются попыткой заменить встроенные документы. Важно убедиться, что новые пользователи R знают, что существуют встроенные документы, а также как их найти.

• Переместите содержимое, применимое к нескольким примерам, в раздел «Примечания».

Стиль

Запрашивает

Если вы хотите, чтобы ваш код был доступен для копирования, удалите приглашения, такие как R> , > или + в начале каждой новой строки. Некоторые авторы Docs предпочитают не делать скопирования в скором времени, и это нормально.

Консольный выход

Консольный выход должен четко отличаться от кода. Общие подходы включают:

• Включать подсказки на входе (как видно при использовании консоли).
• Прокомментируйте все выходные данные: # или ## начиная каждую строку.
• Печатать как есть, доверяя ведущему [1] чтобы выход выделялся из входа.
• Добавьте пустую строку между кодом и выходом консоли.

присваивание

= и <- отлично подходят для назначения объектов R. Используйте пробел должным образом, чтобы избежать написания кода, который трудно разобрать, например x<-1 (неоднозначный между x <- 1 и x < -1 )

Комментарии кодов

Обязательно объясните цель и функцию самого кода. Не существует жесткого правила о том, должно ли это объяснение быть в прозе или в комментариях к коду. Проза может быть более читаемой и позволяет более подробные объяснения, но комментарии коментариев упрощают копирование. Помните оба варианта.

Разделы

Многие примеры достаточно коротки, чтобы не требовать секций, но если вы их используете, начните с H1 .