commit 94680b914780159ad4093917b0a9de9acc8e147a
parent 5ee66e9373fe024aba8b45d7e9e5afd7719158d7
Author: Jake Bauer <jbauer@paritybit.ca>
Date: Thu, 2 Mar 2023 10:58:04 -0500
*
Diffstat:
2 files changed, 57 insertions(+), 31 deletions(-)
diff --git a/content/garden/kitchen-equipment.md b/content/garden/kitchen-equipment.md
@@ -41,7 +41,8 @@ The large, flat blade also doubles as a bench scraper allowing you to chop and
transfer with ease.
I'm a fan of the CCK1303, but there are plenty of other models out there.
-Whichever knife you choose, do some research before you buy
+Mercer, Dexter, Victorinox, and Shibazi are all commonly recommended brands
+alongside CCK. Whichever knife you choose, do some research before you buy
([r/chefknives](https://old.reddit.com/r/chefknives) is great for this). This
is a tool you're likely going to use every day and if it frustrates you then
cooking becomes a chore instead of something fun.
diff --git a/content/garden/programming-style.md b/content/garden/programming-style.md
@@ -36,8 +36,12 @@ gofmt or Python's PEP 8), abide by that style.
<li><a href="#language-specifics">Language Specifics</a></li>
</ul>
-Also see: [Clean Coders Hate What Happens to Your Code When You Use These
+Also see:
+
+* [Clean Coders Hate What Happens to Your Code When You Use These
Enterprise Programming Tricks](https://www.youtube.com/watch?v=FyCYva9DhsI)
+* [Seven Ineffective Coding Habits of Many Programmers](https://www.youtube.com/watch?v=ZsHMHukIlJY)
+* ["Clean" Code, Horrible Performance](https://www.youtube.com/watch?v=tD5NrevFtbU)
## Dependencies
@@ -158,9 +162,6 @@ len = length_computer(x);
if (check_length(len))
```
-Also see: [What is the difference between a function and
-a procedure?](https://stackoverflow.com/questions/721090/what-is-the-difference-between-a-function-and-a-procedure#721107).
-
Names like `maximumValueUntilOverflow` or `EntertainmentProviderViewController`
are bad. They are excessive and make it harder to see what the program is
actually doing. Also, the latter example is annoyingly vague and indirect.
@@ -175,8 +176,17 @@ over `max_val`, but not `percenttrue` over `percent_true`.
Also, if variables represent specific units of a measurement (e.g. milliseconds
or kilometers), this should be reflected in its name. This is also why
-`snake_case` is preferable to `camelCase` for variables. `timeMs` or `timeMS`
-looks worse than `time_ms`.
+`snake_case` is preferable to `camelCase` for variables. `timeMs`, `timeMS` or
+`timeMilliseconds` look worse than `time_ms`.
+
+Another reason why `snake_case` is preferable is that it eliminates the need to
+decide whether acronyms should be capitalized. Should you write
+`fetchRssFeedAsXml` or `fetchRSSFeedAsXML`? Eliminate the need to make that
+decision by just writing `fetch_rss_feed_as_xml`. Whatever you do, please don't
+mix the two (`XMLHttpRequest` is a classic real-world example, probably done
+because nothing else looked better, but `xml_http_request` looks just fine and
+doesn't make capital letters play double-duty as word boundary markers and as
+abbreviations).
Furthermore, it is acceptable to use short names where the meaning is
immediately clear from the context. For example, `np` is better than
@@ -217,6 +227,12 @@ filename = "file.txt"
CoordinatePair updated_coordinate = (compute_x(x), y)
```
+### References
+
+* [snake\_case\_is\_the\_best\_case](https://pedrocattori.dev/blog/snake-case-is-the-best-case)
+* [What is the difference between a function and
+a procedure?](https://stackoverflow.com/questions/721090/what-is-the-difference-between-a-function-and-a-procedure#721107)
+
## Braces and Parentheses
Braces and parentheses should be used liberally to make code easy to follow.
@@ -287,8 +303,8 @@ if (condition) {
}
```
-it is far more readable in general to put opening braces on a new line ([Allman
-Style](https://en.wikipedia.org/wiki/Indentation_style#Allman_style)):
+it is far more readable in general to put opening braces on a new line,
+([Allman Style](https://en.wikipedia.org/wiki/Indentation_style#Allman_style)):
```
if (condition)
@@ -312,7 +328,7 @@ if (is_logged_in(client)
}
```
-is far better than:
+is far nicer than:
```
if (is_logged_in(client)
@@ -407,7 +423,7 @@ visually line up.
With this style, it is much easier to keep track of block boundaries when the
braces are distinctly on their own lines. It also means that, should the
conditions in an `if` statement or the arguments to a function grow too long to
-fit comfortably on one line, there is still meaningful separation between the
+fit comfortably on one line, there is still noticeable separation between the
function's declaration and its body without an additional level of indentation.
While some might denounce this style because it's not as compact and one can't
@@ -424,9 +440,9 @@ a hard limit on the length of lines.
However, one should strive to keep lines within a reasonable length, such that
one does not have to scroll a reasonably-sized editor to see the ends of
-a line. Smaller line lengths are also easier for people to read since long
+a line. Shorter line lengths are also easier for people to read since long
lines make it harder to find the beginning of the next line. While this mostly
-applies to prose, it also applies to code in some circumstances (e.g. code
+applies to prose, it also applies to code in many circumstances (e.g. code
comments or dense blocks of code that are awkward to split up). Plus, limiting
the length of your lines to something reasonable allows one to have two or
three windows side-by-side without needing to scroll.
@@ -451,8 +467,9 @@ this_is_a_function_with_a_long_name(int param1, int param2, int param3, int para
```
int
-this_is_a_function_with_a_long_name(int param1, int param2, int param3,
- int param4, int param5, int param6, int param7, int param8)
+this_is_a_function_with_a_long_name(
+ int param1, int param2, int param3, int param4,
+ int param5, int param6, int param7, int param8)
{
return CONSTANT + max(param1, param2, param3, param4, param5, param6, param7, param8);
}
@@ -468,12 +485,15 @@ from Linus Torvalds) is that "if you need more than 3 levels of indentation,
you’re screwed anyway, and should fix your program." While this is not
a hard-and-fast rule, especially for programming languages which have functions
inside of class definitions and so on, it is a decent guideline for writing the
-logic of your code, since excessive levels of indentation probably indicates
-inefficient checking of conditions or heavily-nested loops which tend to be
-quite slow.
+logic of your code, since an excessive level of indentation probably indicates
+inefficient use of conditionals or heavily-nested loops which tend to be quite
+slow.
+
+Regarding spacing in a statement, there should be spaces between binary or
+trinary operators (but not unary operators) and their operands as well as
+between elements in a list:
-There should be spaces between binary or trinary operators (but not unary
-operators) and their operands as well as between elements in a list:
+### Better
```
array = [1, 2, 3, 4];
@@ -483,7 +503,7 @@ for (i = 0; i < 10; ++i) {
}
```
-not:
+### Worse
```
array=[1,2,3,4];
@@ -494,17 +514,18 @@ for(i=0;i<10;++i){
```
Also, it is acceptable to use spaces to visually align your code if it makes it
-easier to read (not tabs, their variable width makes them inconsistent for this purpose). Once again, use your judgement. Oftentimes no alignment is
-really needed (plus, it makes no difference if you like to program with
-a variable-width font).
+easier to read (but do not use tabs, their variable width makes them
+inconsistent for this purpose). Once again, use your judgement. Oftentimes no
+alignment is really needed and it makes things look worse for those who like to
+program with a variable-width font.
Now, onto The Debate™...
There is little difference between spaces and tabs for indentation. Although
some people might cry "accessibility!" as an argument for tabs over spaces,
there is no significant evidence to support this assertion and I have seen
-accessibility anecdotes for both. Unless someone does an actual study on this,
-I will continue to assert that there is little meaningful difference.
+accessibility anecdotes for both. Unless someone some kind of actual study on
+this, I will continue to assert that there is little meaningful difference.
That being said, I prefer tabs wherever supported for the following reasons:
@@ -519,8 +540,10 @@ still isn't. Even on files that are only a couple of hundreds of lines long,
using spaces instead of tabs to indent increases file size by a decent amount.
If you're trying to optimize the size of assets you're delivering over the wire
(e.g. HTML, CSS, and JS files), this is even more pertinent. For example, this
-page as a tab-indented HTML file takes up XXXX bytes, but it takes up XXXX
-bytes if indented with four spaces.
+page as an HTML file indented with four spaces takes up roughly 33.3 kilobytes,
+but it only takes up 23.1 kilobytes if indented with tabs. This quickly
+compounds the more data is sent over the wire and affects everything from
+serving websites to cloning code repositories.
On the second point, if a programmer prefers to see a lot of whitespace to
indicate levels of indentation (as I do), they can choose to leave tabs at
@@ -534,16 +557,18 @@ Regardless of any other points, nobody should be using mixed indentation or two
spaces for indentation. Mixed indentation makes it difficult to follow blocks
of code (please don't indent your braces two spaces and the body of a block
four spaces) and two spaces is harder to read than four because of the lack of
-whitespace to differentiate indentation levels.
+whitespace to differentiate between indentation levels.
Given that there is no inherent advantage to spaces over tabs aside from the
fact that a space takes up the same width for every programmer (not that this
-is important given my previous points about levels of indentation and line
+is important given my previous points about programmer preference and line
lengths), it is easy to see why tabs are preferred.
### References
-* [Tabs versus spaces—what is the proper indentation character for everything, in every situation, ever?](https://softwareengineering.stackexchange.com/questions/57)
+* [Tabs versus spaces—what is the proper indentation character for everything,
+in every situation,
+ever?](https://softwareengineering.stackexchange.com/questions/57)
## Language Specifics
