Back to Details

r-package-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

R package development

R包开发

Key commands

核心命令

undefined
undefined

Run code in the package

Run code in the package

Rscript -e "devtools::load_all(); code"
Rscript -e "devtools::load_all(); code"

Run all tests

Run all tests

Rscript -e "devtools::test()"
Rscript -e "devtools::test()"

Run all tests for files starting with {name}

Run all tests for files starting with {name}

Rscript -e "devtools::test(filter = '^{name}')"
Rscript -e "devtools::test(filter = '^{name}')"

Run all tests for R/{name}.R

Run all tests for R/{name}.R

Rscript -e "devtools::test_active_file('R/{name}.R')"
Rscript -e "devtools::test_active_file('R/{name}.R')"

Run a single test "blah" for R/{name}.R

Run a single test "blah" for R/{name}.R

Rscript -e "devtools::test_active_file('R/{name}.R', desc = 'blah')"
Rscript -e "devtools::test_active_file('R/{name}.R', desc = 'blah')"

Redocument the package

Redocument the package

Rscript -e "devtools::document()"
Rscript -e "devtools::document()"

Check pkgdown documentation

Check pkgdown documentation

Rscript -e "pkgdown::check_pkgdown()"
Rscript -e "pkgdown::check_pkgdown()"

Check the package with R CMD check

Check the package with R CMD check

Rscript -e "devtools::check()"
Rscript -e "devtools::check()"

Format code

Format code

air format .
undefined
air format .
undefined

Coding

编码规范

  • Always run 
    air format .
    after generating code.
  • Use the base pipe operator (
    |>
    ) not the magrittr pipe (
    %>
    ).
  • Use 
    \() ...
    for single-line anonymous functions. For all other cases, use 
    function() {...}
    .
  • 生成代码后务必运行
    air format .
    。
  • 使用基础管道操作符(
    |>
    )而非magrittr管道操作符(
    %>
    )。
  • 单行匿名函数使用
    \() ...
    。其他所有情况使用
    function() {...}
    。

Testing

测试规范

  • Tests for 
    R/{name}.R
    go in 
    tests/testthat/test-{name}.R
    .
  • All new code should have an accompanying test.
  • If there are existing tests, place new tests next to similar existing tests.
  • Strive to keep tests minimal with few comments.
  • Avoid 
    expect_true()
    and 
    expect_false()
    in favour of a specific expectation which will give a better failure message.
  • When testing errors and warnings, don't use 
    expect_error()
    or 
    expect_warning()
    . Instead, use 
    expect_snapshot(error = TRUE)
    for errors and 
    expect_snapshot()
    for warnings because these allow the user to review the full text of the output.
  • 针对
    R/{name}.R
    的测试应放在
    tests/testthat/test-{name}.R
    中。
  • 所有新增代码都应配备对应的测试。
  • 如果已有测试，将新测试放在类似的现有测试旁边。
  • 尽量保持测试简洁，减少注释。
  • 避免使用
    expect_true()
    和
    expect_false()
    ，改用更具体的断言，这样能提供更清晰的失败信息。
  • 测试错误和警告时，不要使用
    expect_error()
    或
    expect_warning()
    。而是对错误使用
    expect_snapshot(error = TRUE)
    ，对警告使用
    expect_snapshot()
    ，因为这些方法允许用户查看输出的完整文本。

Documentation

文档规范

  • Every user-facing function should be exported and have roxygen2 documentation.
  • Wrap roxygen comments at 80 characters.
  • Internal functions should not have roxygen documentation.
  • Whenever you add a new (non-internal) documentation topic, also add the topic to 
    _pkgdown.yml
    .
  • Always re-document the package after changing a roxygen2 comment.
  • Use 
    pkgdown::check_pkgdown()
    to check that all topics are included in the reference index.
  • 所有面向用户的函数都应导出并配备roxygen2文档。
  • roxygen注释每行不超过80个字符。
  • 内部函数无需配备roxygen文档。
  • 每当添加新的（非内部）文档主题时，需将该主题添加到
    _pkgdown.yml
    中。
  • 修改roxygen2注释后务必重新生成包文档。
  • 使用
    pkgdown::check_pkgdown()
    检查所有主题是否都已包含在参考索引中。

NEWS.md

NEWS.md
规范

  • Every user-facing change should be given a bullet in 
    NEWS.md
    . Do not add bullets for small documentation changes or internal refactorings.
  • Each bullet should briefly describe the change to the end user and mention the related issue in parentheses.
  • A bullet can consist of multiple sentences but should not contain any new lines (i.e. DO NOT line wrap).
  • If the change is related to a function, put the name of the function early in the bullet.
  • Order bullets alphabetically by function name. Put all bullets that don't mention function names at the beginning.
  • 所有面向用户的变更都应在
    NEWS.md
    中添加一个项目符号。小的文档变更或内部重构无需添加。
  • 每个项目符号应简要向终端用户描述变更内容，并在括号中提及相关问题编号。
  • 一个项目符号可以包含多个句子，但不能有换行（即不要换行拆分）。
  • 如果变更与某个函数相关，应在项目符号开头提及函数名称。
  • 项目符号按函数名称字母顺序排列。所有未提及函数名称的项目符号放在最前面。