R Packages Organize, Test, Document, and Share Your Code (Hadley Wickham, Jennifer Bryan)（Z-Library）

【One-Line Pitch】 A practical, hands-on guide for R users who want to turn scattered scripts into well-organized, testable, and shareable packages, written by the creators of the tidyverse toolchain. Ideal for data scientists and developers who have written R code and now want to professionalize it with modern tools like devtools, usethis, testthat, and roxygen2. 【Book Arc】 - **Opening (~0%–9%)**: Introduces the core philosophy that packages are the fundamental units of reproducible R code, and outlines the major updates in this edition, including the "conscious uncoupling" of devtools into smaller packages and new coverage of package websites and GitHub Actions. - **Early (~9%–25%)**: Walks through "The Whole Game"—a complete end-to-end example of creating a package from scratch, including system setup (Rtools on Windows, Xcode on macOS, r-base-dev on Linux), the initial file structure, and the first use of usethis functions to scaffold a project. - **Early (~25%–34%)**: Dives into the practical mechanics of package development, such as declaring dependencies with use_package(), adopting naming conventions, and understanding the role of DESCRIPTION and NAMESPACE files in managing package metadata and imports. - **Middle (~34%–47%)**: Covers foundational workflows and common pitfalls, including how to choose a good package name, the difference between build time and run time (with a memorable "Foxtrot" example showing why top-level assignments like `now <- Sys.time()` are dangerous), and why shipping data files requires special handling. - **Middle (~47%–53%)**: Continues with deeper lessons on package structure, emphasizing that most objects in a package should be functions that only use data they create or receive via arguments, and introduces the concept of testing with testthat as a core part of the development cycle. 【Key Takeaways】 - **Packages are the unit of reproducibility** (Opening): The book's central claim is that bundling functions, documentation, and sample data into a package is the best way to make R code reliable and shareable. This frames everything that follows. - **Start with a working skeleton, then improve** (Early): The "Whole Game" chapter deliberately shows a minimal but complete package workflow, reinforcing that your first version doesn't need to be perfect—just better than the last. This lowers the barrier to entry for beginners. - **System setup is platform-specific but essential** (Early): Windows users need Rtools (without editing PATH), macOS users need Xcode command-line tools, and Linux users need r-base-dev. Getting this right avoids frustrating build failures later. - **Dependencies should be declared, not assumed** (Early): Using `use_package("stringr")` adds the package to DESCRIPTION's Imports field, and the book recommends calling functions with `package::function()` syntax for clarity and namespace safety. - **Package names matter more than you think** (Middle): A good name is unique, Googleable, pronounceable, and avoids trademark issues. The book gives concrete examples like lubridate, rvest, and forcats to illustrate naming strategies. - **Build time vs. run time is a critical distinction** (Middle): The "Foxtrot" example shows that top-level assignments like `now <- Sys.time()` are evaluated at build time, not when the user runs the function. This is a subtle but crucial lesson for writing correct package code. - **Most package objects should be functions** (Middle): The book stresses that functions should only use data they create or receive via arguments, avoiding hidden global state that can break when code is distributed as a package. 【Reading Tips】 - **Skim the preface and "Whole Game" chapter first** (~0%–25%): These give you the big picture and a complete worked example, so you understand the end-to-end workflow before diving into details. You can always return to specifics later. - **Deep-read the "Foxtrot" example** (~47%): This is one of the most instructive parts of the book because it shows a realistic mistake (using `Sys.time()` at build time) and how to fix it. Understanding this will save you from a common class of bugs. - **Treat the system setup chapter as a checklist** (~9%–16%): Don't read it linearly—just find your operating system and follow the instructions. This is reference material, not narrative. - **Pay attention to the naming and dependency chapters** (~34%–44%): These are short but packed with practical advice that will save you pain later, especially if you plan to release your package publicly. - **Use the online version for code examples** (throughout): The book mentions that the electronic version at r-pkgs.org allows easy copy-paste of examples, which is invaluable when you're following along in your own R session. 【Coverage Limits】 This guide synthesizes the opening and early-middle portions of the book (roughly the first half). The excerpts do not cover the later chapters on testing with testthat, documentation with roxygen2, package websites with pkgdown, or GitHub Actions in detail—those topics are mentioned but not explored in depth here.