R Language
Meta: Руководство по документации
Поиск…
замечания
Чтобы обсудить редактирование документов тегов R, зайдите в чат R.
Хорошие примеры
Большинство рекомендаций по созданию хороших примеров для вопросов и ответов переносятся в документацию.
Сделайте его минимальным и дойдете до сути. Осложнения и отступления являются контрпродуктивными.
Включите как рабочий код, так и прозу, объясняющие его. Ни один из них не является достаточным.
Не полагайтесь на внешние источники данных. Создайте данные или используйте библиотеку наборов данных, если это возможно:
library(help = "datasets")
В контексте Документов есть несколько дополнительных соображений:
Обратитесь к встроенным документам типа
?data.frameесли это необходимо. SO Docs не являются попыткой заменить встроенные документы. Важно убедиться, что новые пользователи R знают, что существуют встроенные документы, а также как их найти.Переместите содержимое, применимое к нескольким примерам, в раздел «Примечания».
Стиль
Запрашивает
Если вы хотите, чтобы ваш код был доступен для копирования, удалите приглашения, такие как R> , > или + в начале каждой новой строки. Некоторые авторы Docs предпочитают не делать скопирования в скором времени, и это нормально.
Консольный выход
Консольный выход должен четко отличаться от кода. Общие подходы включают:
- Включать подсказки на входе (как видно при использовании консоли).
- Прокомментируйте все выходные данные:
#или##начиная каждую строку. - Печатать как есть, доверяя ведущему
[1]чтобы выход выделялся из входа. - Добавьте пустую строку между кодом и выходом консоли.
присваивание
= и <- отлично подходят для назначения объектов R. Используйте пробел должным образом, чтобы избежать написания кода, который трудно разобрать, например x<-1 (неоднозначный между x <- 1 и x < -1 )
Комментарии кодов
Обязательно объясните цель и функцию самого кода. Не существует жесткого правила о том, должно ли это объяснение быть в прозе или в комментариях к коду. Проза может быть более читаемой и позволяет более подробные объяснения, но комментарии коментариев упрощают копирование. Помните оба варианта.
Разделы
Многие примеры достаточно коротки, чтобы не требовать секций, но если вы их используете, начните с H1 .
