course/r4ds
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Re-render book for O'Reilly

Browse Source
This commit is contained in:
Hadley Wickham
2023-01-12 17:22:57 -06:00
parent 28671ed8bd
commit 360d65ae47
113 changed files with 4957 additions and 2997 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
oreilly/workflow-style.html
View File

@@ -1,5 +1,5 @@
<section data-type="chapter" id="chp-workflow-style">
<h1><span id="sec-workflow-style" class="quarto-section-identifier d-none d-lg-block"><span class="chapter-title">Workflow: code style</span></span></h1><p>Good coding style is like correct punctuation: you can manage without it, butitsuremakesthingseasiertoread. Even as a very new programmer it’s a good idea to work on your code style. Using a consistent style makes it easier for others (including future-you!) to read your work, and is particularly important if you need to get help from someone else. This chapter will introduce to the most important points of the <a href="https://style.tidyverse.org">tidyverse style guide</a>, which is used throughout this book.</p><p>Styling your code will feel a bit tedious to start with, but if you practice it, it will soon become second nature. Additionally, there are some great tools to quickly restyle existing code, like the <a href="https://styler.r-lib.org">styler</a> package by Lorenz Walthert. Once you’ve installed it with <code>install.packages("styler")</code>, an easy way to use it is via RStudio’s <strong>command palette</strong>. The command palette lets you use any build-in RStudio command, as well as many addins provided by packages. Open the palette by pressing Cmd/Ctrl + Shift + P, then type “styler” to see all the shortcuts provided by styler. <a href="#fig-styler" data-type="xref">#fig-styler</a> shows the results.</p><div class="cell">
<h1><span id="sec-workflow-style" class="quarto-section-identifier d-none d-lg-block"><span class="chapter-title">Workflow: code style</span></span></h1><p>Good coding style is like correct punctuation: you can manage without it, butitsuremakesthingseasiertoread. Even as a very new programmer, it’s a good idea to work on your code style. Using a consistent style makes it easier for others (including future-you!) to read your work and is particularly important if you need to get help from someone else. This chapter will introduce the most important points of the <a href="https://style.tidyverse.org">tidyverse style guide</a>, which is used throughout this book.</p><p>Styling your code will feel a bit tedious to start with, but if you practice it, it will soon become second nature. Additionally, there are some great tools to quickly restyle existing code, like the <a href="https://styler.r-lib.org"><strong>styler</strong></a> package by Lorenz Walthert. Once you’ve installed it with <code>install.packages("styler")</code>, an easy way to use it is via RStudio’s <strong>command palette</strong>. The command palette lets you use any built-in RStudio command and many addins provided by packages. Open the palette by pressing Cmd/Ctrl + Shift + P, then type “styler” to see all the shortcuts offered by styler. <a href="#fig-styler" data-type="xref">#fig-styler</a> shows the results.</p><div class="cell">
<div class="cell-output-display">
<figure id="fig-styler"><p><img src="screenshots/rstudio-palette.png" alt="A screenshot showing the command palette after typing &quot;styler&quot;, showing the four styling tool provided by the package." width="638"/></p>
@@ -21,14 +21,14 @@ short_flights &lt;- flights |&gt; filter(air_time &lt; 60)
# Avoid:
SHORTFLIGHTS &lt;- flights |&gt; filter(air_time &lt; 60)</pre>
</div>
<p>As a general rule of thumb, it’s better to prefer long, descriptive names that are easy to understand, rather than concise names that are fast to type. Short names save relatively little time when writing code (especially since autocomplete will help you finish typing them), but can be time-consuming when you come back to old code and are forced to puzzle out a cryptic abbreviation.</p>
<p>If you have a bunch of names for related things, do your best to be consistent. It’s easy for inconsistencies to arise when you forget a previous convention, so don’t feel bad if you have to go back and rename things. In general, if you have a bunch of variables that are a variation on a theme you’re better off giving them a common prefix, rather than a common suffix, because autocomplete works best on the start of a variable.</p>
<p>As a general rule of thumb, it’s better to prefer long, descriptive names that are easy to understand rather than concise names that are fast to type. Short names save relatively little time when writing code (especially since autocomplete will help you finish typing them), but it can be time-consuming when you come back to old code and are forced to puzzle out a cryptic abbreviation.</p>
<p>If you have a bunch of names for related things, do your best to be consistent. It’s easy for inconsistencies to arise when you forget a previous convention, so don’t feel bad if you have to go back and rename things. In general, if you have a bunch of variables that are a variation on a theme, you’re better off giving them a common prefix rather than a common suffix because autocomplete works best on the start of a variable.</p>
</section>
<section id="spaces" data-type="sect1">
<h1>
Spaces</h1>
<p>Put spaces on either side of mathematical operators apart from <code>^</code> (i.e., <code>+</code>, <code>-</code>, <code>==</code>, <code>&lt;</code>, …), and around the assignment operator (<code>&lt;-</code>).</p>
<p>Put spaces on either side of mathematical operators apart from <code>^</code> (i.e. <code>+</code>, <code>-</code>, <code>==</code>, <code>&lt;</code>, …), and around the assignment operator (<code>&lt;-</code>).</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="r"># Strive for
z &lt;- (a + b)^2 / d
@@ -36,7 +36,7 @@ z &lt;- (a + b)^2 / d
# Avoid
z&lt;-( a + b ) ^ 2/d</pre>
</div>
<p>Don’t put spaces inside or outside parentheses for regular function calls. Always put a space after a comma, just like in regular English.</p>
<p>Don’t put spaces inside or outside parentheses for regular function calls. Always put a space after a comma, just like in standard English.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="r"># Strive for
mean(x, na.rm = TRUE)
@@ -58,7 +58,7 @@ mean (x ,na.rm=TRUE)</pre>
<section id="sec-pipes" data-type="sect1">
<h1>
Pipes</h1>
<p><code>|&gt;</code> should always have a space before it and should typically be the last thing on a line. This makes it easier to add new steps, rearrange existing steps, modify elements within a step, and to get a 50,000 ft view by skimming the verbs on the left-hand side.</p>
<p><code>|&gt;</code> should always have a space before it and should typically be the last thing on a line. This makes it easier to add new steps, rearrange existing steps, modify elements within a step, and get a 50,000 ft view by skimming the verbs on the left-hand side.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="r"># Strive for
flights |&gt;
@@ -68,7 +68,7 @@ flights |&gt;
# Avoid
flights|&gt;filter(!is.na(arr_delay), !is.na(tailnum))|&gt;count(dest)</pre>
</div>
<p>If the function you’re piping into has named arguments (like <code><a href="https://dplyr.tidyverse.org/reference/mutate.html">mutate()</a></code> or <code><a href="https://dplyr.tidyverse.org/reference/summarise.html">summarize()</a></code>), put each argument on a new line. If the function doesn’t have named arguments (like <code><a href="https://dplyr.tidyverse.org/reference/select.html">select()</a></code> or <code><a href="https://dplyr.tidyverse.org/reference/filter.html">filter()</a></code>) keep everything on one line unless it doesn’t fit, in which case you should put each argument on its own line.</p>
<p>If the function you’re piping into has named arguments (like <code><a href="https://dplyr.tidyverse.org/reference/mutate.html">mutate()</a></code> or <code><a href="https://dplyr.tidyverse.org/reference/summarise.html">summarize()</a></code>), put each argument on a new line. If the function doesn’t have named arguments (like <code><a href="https://dplyr.tidyverse.org/reference/select.html">select()</a></code> or <code><a href="https://dplyr.tidyverse.org/reference/filter.html">filter()</a></code>), keep everything on one line unless it doesn’t fit, in which case you should put each argument on its own line.</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="r"># Strive for
flights |&gt;
@@ -135,11 +135,11 @@ ggplot2</h1>
summarize(
delay = mean(arr_delay, na.rm = TRUE)
) |&gt;
ggplot(aes(month, delay)) +
ggplot(aes(x = month, y = delay)) +
geom_point() +
geom_line()</pre>
</div>
<p>Again, if you can fit all of the arguments to a function on to a single line, put each argument on its own line:</p>
<p>Again, if you can’t fit all of the arguments to a function on to a single line, put each argument on its own line:</p>
<div class="cell">
<pre data-type="programlisting" data-code-language="r">flights |&gt;
group_by(dest) |&gt;
@@ -147,7 +147,7 @@ ggplot2</h1>
distance = mean(distance),
speed = mean(air_time / distance, na.rm = TRUE)
) |&gt;
ggplot(aes(distance, speed)) +
ggplot(aes(x = distance, y = speed)) +
geom_smooth(
method = "loess",
span = 0.5,