Mention the Principle of Least Astonishment #90
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
katrinleinweber
commented
Jun 26, 2019
| script can run cleanly. But if someone else `source()`s your script, it will | ||
| delete objects that might be important to them. (Of course, you'd hope that | ||
| all of those objects could easily be recreated from another script, but that | ||
| is not always the case). | ||
|
|
||
| Because R doesn't constrain the potential scope of functions and scripts, *you* have to. By avoiding these actions, you will create code that is less suprising to other R users. At first, this might seem like tedious busywork. You might find that spooky action is convenient in the moment, and you might convince yourself that it’s necessary or a good idea. But as you share your code with more people and run more code that has been shared with you[^teachers], you'll find spooky action to get more and more surprising and frustrating. | ||
| Because R doesn't constrain the potential scope of functions and scripts, *you* have to. By avoiding these actions, you will create code that is less surprising to other R users. Moreover, you'll benefit from the experience of other programming pioneers, summarised in the "Principle of Least Astonishment/Surprise" (POLA[^pola]). |
There was a problem hiding this comment.
I hope this doesn't sound too cheesy.
There was a problem hiding this comment.
One thing I'd like to touch on (but I don't yet know how), is that this is also establishing what you should be surprised be. IOTW, you can only be surprised by something if you have a strong prior expectation, and part of this principle is establishing that your expectation should be that functions act locally.
katrinleinweber
commented
Jun 26, 2019
| Because R doesn't constrain the potential scope of functions and scripts, *you* have to. By avoiding these actions, you will create code that is less suprising to other R users. At first, this might seem like tedious busywork. You might find that spooky action is convenient in the moment, and you might convince yourself that it’s necessary or a good idea. But as you share your code with more people and run more code that has been shared with you[^teachers], you'll find spooky action to get more and more surprising and frustrating. | ||
| Because R doesn't constrain the potential scope of functions and scripts, *you* have to. By avoiding these actions, you will create code that is less surprising to other R users. Moreover, you'll benefit from the experience of other programming pioneers, summarised in the "Principle of Least Astonishment/Surprise" (POLA[^pola]). | ||
|
|
||
| [^pola]: https://web.archive.org/web/20181216083109/http://wiki.c2.com/?PrincipleOfLeastAstonishment |
There was a problem hiding this comment.
This reference could be updated to https://en.wikipedia.org/wiki/Principle_of_least_astonishment or a new version of the C2Wiki.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Includes #88, so please merge that one 1st or close it.
See https://github.com/tidyverse/principles/pull/90/files#diff-80b7d431843e2948b25a9583860511afL33 for diff & some comments.