Skip to content

Commit

Permalink
add thumbnail
Browse files Browse the repository at this point in the history
  • Loading branch information
@yjunechoe
yjunechoe committed Sep 1, 2024
1 parent 27522ba commit 8843f80
Show file tree
Hide file tree
Showing 44 changed files with 4,089 additions and 3,742 deletions.
3 changes: 2 additions & 1 deletion _posts/2024-07-21-enumerate-possible-options/enumerate-possible-options.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ output:
css: "../../styles.css"
editor_options:
chunk_output_type: console
preview: preview.jpg
---

```{r setup, include=FALSE}
Expand Down Expand Up @@ -161,7 +162,7 @@ fun(optimizer = "MyOptim")
fun(optimizer = "none")
```

Of course, the more difficult case is when the thing that's being toggled isn't really nameable. I think this is more often the case in practice, and may be the reason why there are many verb-y names for arguments with boolean options. Like, you wrote some code that optimizes something, but you have no name for it, so the argument that toggles it simple refers to its function like "should the function `optimize`?".
Of course, the more difficult case is when the thing that's being toggled isn't really nameable. I think this is more often the case in practice, and may be the reason why there are many verb-y names for arguments with boolean options. Like, you wrote some code that optimizes something, but you have no name for it, so the argument that toggles it simply refers to its function, like "should the function `optimize`?".

But not all is lost. I think one way out of this would be to enumerate over placeholders, not necessarily names. So something like:

Expand Down
22 changes: 12 additions & 10 deletions _posts/2024-07-21-enumerate-possible-options/enumerate-possible-options.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -94,31 +94,33 @@


<!-- https://schema.org/Article -->
<meta property="article:published" itemprop="datePublished" content="2024-07-21"/>
<meta property="article:created" itemprop="dateCreated" content="2024-07-21"/>
<meta property="article:published" itemprop="datePublished" content="2024-09-01"/>
<meta property="article:created" itemprop="dateCreated" content="2024-09-01"/>
<meta name="article:author" content="June Choe"/>

<!-- https://developers.facebook.com/docs/sharing/webmasters#markup -->
<meta property="og:title" content="Naming patterns for boolean enums"/>
<meta property="og:type" content="article"/>
<meta property="og:description" content="Some thoughts on the principle of enumerating possible options, even for booleans"/>
<meta property="og:image" content="https://yjunechoe.github.io/preview.jpg"/>
<meta property="og:locale" content="en_US"/>

<!-- https://dev.twitter.com/cards/types/summary -->
<meta property="twitter:card" content="summary"/>
<meta property="twitter:card" content="summary_large_image"/>
<meta property="twitter:title" content="Naming patterns for boolean enums"/>
<meta property="twitter:description" content="Some thoughts on the principle of enumerating possible options, even for booleans"/>
<meta property="twitter:image" content="https://yjunechoe.github.io/preview.jpg"/>

<!--/radix_placeholder_meta_tags-->
<!--radix_placeholder_rmarkdown_metadata-->

<script type="text/json" id="radix-rmarkdown-metadata">
{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["title","description","categories","base_url","author","date","output","editor_options"]}},"value":[{"type":"character","attributes":{},"value":["Naming patterns for boolean enums"]},{"type":"character","attributes":{},"value":["Some thoughts on the principle of enumerating possible options, even for booleans\n"]},{"type":"character","attributes":{},"value":["design"]},{"type":"character","attributes":{},"value":["https://yjunechoe.github.io"]},{"type":"list","attributes":{},"value":[{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["name","affiliation","affiliation_url","orcid_id"]}},"value":[{"type":"character","attributes":{},"value":["June Choe"]},{"type":"character","attributes":{},"value":["University of Pennsylvania Linguistics"]},{"type":"character","attributes":{},"value":["https://live-sas-www-ling.pantheon.sas.upenn.edu/"]},{"type":"character","attributes":{},"value":["0000-0002-0701-921X"]}]}]},{"type":"character","attributes":{},"value":["2024-07-21"]},{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["distill::distill_article"]}},"value":[{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["include-after-body","toc","self_contained","css"]}},"value":[{"type":"character","attributes":{},"value":["highlighting.html"]},{"type":"logical","attributes":{},"value":[true]},{"type":"logical","attributes":{},"value":[false]},{"type":"character","attributes":{},"value":["../../styles.css"]}]}]},{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["chunk_output_type"]}},"value":[{"type":"character","attributes":{},"value":["console"]}]}]}
{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["title","description","categories","base_url","author","date","output","editor_options","preview"]}},"value":[{"type":"character","attributes":{},"value":["Naming patterns for boolean enums"]},{"type":"character","attributes":{},"value":["Some thoughts on the principle of enumerating possible options, even for booleans\n"]},{"type":"character","attributes":{},"value":["design"]},{"type":"character","attributes":{},"value":["https://yjunechoe.github.io"]},{"type":"list","attributes":{},"value":[{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["name","affiliation","affiliation_url","orcid_id"]}},"value":[{"type":"character","attributes":{},"value":["June Choe"]},{"type":"character","attributes":{},"value":["University of Pennsylvania Linguistics"]},{"type":"character","attributes":{},"value":["https://live-sas-www-ling.pantheon.sas.upenn.edu/"]},{"type":"character","attributes":{},"value":["0000-0002-0701-921X"]}]}]},{"type":"character","attributes":{},"value":["2024-09-01"]},{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["distill::distill_article"]}},"value":[{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["include-after-body","toc","self_contained","css"]}},"value":[{"type":"character","attributes":{},"value":["highlighting.html"]},{"type":"logical","attributes":{},"value":[true]},{"type":"logical","attributes":{},"value":[false]},{"type":"character","attributes":{},"value":["../../styles.css"]}]}]},{"type":"list","attributes":{"names":{"type":"character","attributes":{},"value":["chunk_output_type"]}},"value":[{"type":"character","attributes":{},"value":["console"]}]},{"type":"character","attributes":{},"value":["preview.jpg"]}]}
</script>
<!--/radix_placeholder_rmarkdown_metadata-->

<script type="text/json" id="radix-resource-manifest">
{"type":"character","attributes":{},"value":["enumerate-possible-options_files/anchor-4.2.2/anchor.min.js","enumerate-possible-options_files/bowser-1.9.3/bowser.min.js","enumerate-possible-options_files/distill-2.2.21/template.v2.js","enumerate-possible-options_files/header-attrs-2.27/header-attrs.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.min.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.min.map","enumerate-possible-options_files/popper-2.6.0/popper.min.js","enumerate-possible-options_files/tippy-6.2.7/tippy-bundle.umd.min.js","enumerate-possible-options_files/tippy-6.2.7/tippy-light-border.css","enumerate-possible-options_files/tippy-6.2.7/tippy.css","enumerate-possible-options_files/tippy-6.2.7/tippy.umd.min.js","enumerate-possible-options_files/webcomponents-2.0.0/webcomponents.js"]}
{"type":"character","attributes":{},"value":["enumerate-possible-options_files/anchor-4.2.2/anchor.min.js","enumerate-possible-options_files/bowser-1.9.3/bowser.min.js","enumerate-possible-options_files/distill-2.2.21/template.v2.js","enumerate-possible-options_files/header-attrs-2.27/header-attrs.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.min.js","enumerate-possible-options_files/jquery-3.6.0/jquery-3.6.0.min.map","enumerate-possible-options_files/popper-2.6.0/popper.min.js","enumerate-possible-options_files/tippy-6.2.7/tippy-bundle.umd.min.js","enumerate-possible-options_files/tippy-6.2.7/tippy-light-border.css","enumerate-possible-options_files/tippy-6.2.7/tippy.css","enumerate-possible-options_files/tippy-6.2.7/tippy.umd.min.js","enumerate-possible-options_files/webcomponents-2.0.0/webcomponents.js","preview.jpg"]}
</script>
<!--radix_placeholder_navigation_in_header-->
<!--/radix_placeholder_navigation_in_header-->
Expand Down Expand Up @@ -1522,7 +1524,7 @@
<!--radix_placeholder_front_matter-->

<script id="distill-front-matter" type="text/json">
{"title":"Naming patterns for boolean enums","description":"Some thoughts on the principle of enumerating possible options, even for booleans","authors":[{"author":"June Choe","authorURL":"#","affiliation":"University of Pennsylvania Linguistics","affiliationURL":"https://live-sas-www-ling.pantheon.sas.upenn.edu/","orcidID":"0000-0002-0701-921X"}],"publishedDate":"2024-07-21T00:00:00.000+09:00","citationText":"Choe, 2024"}
{"title":"Naming patterns for boolean enums","description":"Some thoughts on the principle of enumerating possible options, even for booleans","authors":[{"author":"June Choe","authorURL":"#","affiliation":"University of Pennsylvania Linguistics","affiliationURL":"https://live-sas-www-ling.pantheon.sas.upenn.edu/","orcidID":"0000-0002-0701-921X"}],"publishedDate":"2024-09-01T00:00:00.000-04:00","citationText":"Choe, 2024"}
</script>

<!--/radix_placeholder_front_matter-->
Expand All @@ -1545,7 +1547,7 @@ <h1>Naming patterns for boolean enums</h1>
<div class="d-byline">
June Choe (University of Pennsylvania Linguistics)<a href="https://live-sas-www-ling.pantheon.sas.upenn.edu/" class="uri">https://live-sas-www-ling.pantheon.sas.upenn.edu/</a>

<br/>2024-07-21
<br/>2024-09-01
</div>

<div class="d-article">
Expand Down Expand Up @@ -1655,7 +1657,7 @@ <h2 id="is-the-argument-a-scalar-adjective-consider-naming-the-scale.">Is the ar
<p>I like this strategy of “naming the scale” because it gives off the impression to users that the possible options are values that lie on the scale. In the example above, it could either be the extremes <code>"all"</code> or <code>"none"</code>, but also possibly somewhere in between if the writer of the function chooses to introduce more granular settings later.</p>
<h2 id="is-the-argument-truly-binary-still-prefer-enum-and-name-the-obviousabsence.">Is the argument truly binary? Still prefer enum and name the obvious/absence.</h2>
<p>Sometimes a boolean argument may encode a genuinely binary choice of a true/false, on/off, yes/no option. But refactoring the boolean options as enum may still offer some benefits. In those cases, I prefer the strategy of <strong>name the obvious/absence</strong>.</p>
<p>Some cases for improvement are easier to spot than others. An easy case is something like the <code>REML</code> argument in <code>lme4::lmer()</code>. Without going into too much detail, when <code>REML = TRUE</code> (default), the model optimizes the REML (restricted/residualized maximum likelihood) criterion in finding the best fitting model. But it’s not like the model doesn’t use <em>any</em> criteria for goodness of fit when <code>REML = FALSE</code>. Instead, when <code>REML = FALSE</code>, the function uses a different criterion of ML (maximum likelihood). So the choice is not really between toggling REML on or off, but rather between the choice of REML vs. ML. The enum version lets us spell out the assumed default and make the choice explicit (again, with room for introducing other criteria in the future):</p>
<p>Some cases for improvement are easier to spot than others. An easy case is something like the <code>REML</code> argument in <code>lme4::lmer()</code>. Without going into too much detail, when <code>REML = TRUE</code> (default), the model optimizes the REML (restricted/residualized maximum likelihood) criterion in finding the best fitting model. But it’s not like the model doesn’t use <em>any</em> criteria for goodness of fit when <code>REML = FALSE</code>. Instead, when <code>REML = FALSE</code>, the function uses a different criterion of ML (maximum likelihood). So the choice is not really between toggling REML on or off, but rather between the choice of REML vs. ML. The enum version lets us spell out the assumed default and make the choice between the two explicit (again, with room for introducing other criteria in the future):</p>
<div class="layout-chunk" data-layout="l-body">
<div class="sourceCode">
<pre class="sourceCode r"><code class="sourceCode r"><span><span class='co'># Boolean options</span></span>
Expand All @@ -1667,7 +1669,7 @@ <h2 id="is-the-argument-truly-binary-still-prefer-enum-and-name-the-obviousabsen
<span><span class='fu'>lmer</span><span class='fu'>::</span><span class='fu'>lme4</span><span class='op'>(</span>criterion <span class='op'>=</span> <span class='st'>"ML"</span><span class='op'>)</span></span></code></pre>
</div>
</div>
<p>A somewhat harder cases is a true presence-or-absence kind of a situation, where setting the argument to true/false essentially boils down to triggering an <code>if</code> block inside the function. For example, say a function has an option to use an optimizer called “MyOptim”. This may be implemented as:</p>
<p>A somewhat harder case is a true presence-or-absence kind of a situation, where setting the argument to true/false essentially boils down to triggering an <code>if</code> block inside the function. For example, say a function has an option to use an optimizer called “MyOptim”. This may be implemented as:</p>
<div class="layout-chunk" data-layout="l-body">
<div class="sourceCode">
<pre class="sourceCode r"><code class="sourceCode r"><span><span class='co'># Boolean options</span></span>
Expand All @@ -1683,7 +1685,7 @@ <h2 id="is-the-argument-truly-binary-still-prefer-enum-and-name-the-obviousabsen
<span><span class='fu'>fun</span><span class='op'>(</span>optimizer <span class='op'>=</span> <span class='st'>"none"</span><span class='op'>)</span></span></code></pre>
</div>
</div>
<p>Of course, the more difficult case is when the thing that’s being toggled isn’t really nameable. I think this is more often the case in practice, and may be the reason why there are many verb-y names for arguments with boolean options. Like, you wrote some code that optimizes something, but you have no name for it, so the argument that toggles it simple refers to its function like “should the function <code>optimize</code>?”.</p>
<p>Of course, the more difficult case is when the thing that’s being toggled isn’t really nameable. I think this is more often the case in practice, and may be the reason why there are many verb-y names for arguments with boolean options. Like, you wrote some code that optimizes something, but you have no name for it, so the argument that toggles it simply refers to its function, like “should the function <code>optimize</code>?”.</p>
<p>But not all is lost. I think one way out of this would be to enumerate over placeholders, not necessarily names. So something like:</p>
<div class="layout-chunk" data-layout="l-body">
<div class="sourceCode">
Expand Down
Binary file added _posts/2024-07-21-enumerate-possible-options/preview.jpg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 8843f80

Please sign in to comment.