New chapter: Clear units

content/books/things-i-learnt/_index.md

@@ -51,6 +51,7 @@ template = "section-contentless.html"
 		* [Always Use Timezones With Your Dates](use-timezones)
 		* [Always Use UTF-8 For Your Strings](use-utf8)
 		* [Optimization Is For Compilers](optimization)
+		* [Units Makes Things Clear](units)
 	* Making Things Go
 		* [The Config File Is Friend](config-file)
 		* [Command Line Options Are Weird, But Helpful](command-line-options)

content/books/things-i-learnt/config-file/index.md

@@ -52,4 +52,4 @@ you'll find that you're half-way through it.
 [^1]: In other words, they have a [time to
   live](https://en.wikipedia.org/wiki/Time_to_live).
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/optimization", prev_chapter_title="Optimization Is For Compilers", next_chapter_link="/books/things-i-learnt/command-line-options", next_chapter_title="Command Line Options Are Weird, But Helpful") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/units", prev_chapter_title="Units Makes Things Clear", next_chapter_link="/books/things-i-learnt/command-line-options", next_chapter_title="Command Line Options Are Weird, But Helpful") }}

content/books/things-i-learnt/optimization/index.md

@@ -35,5 +35,4 @@ Code is written for humans to read. _ALWAYS_. Optimization is what compilers
 do. So find a smarter way to explain what you're trying to do instead of using
 shorter words or messing with that your code is saying.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/config-file", next_chapter_title="The Config File Is Friend") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/units", next_chapter_title="Units Makes Things Clear") }}
-

content/books/things-i-learnt/units/index.md

@@ -0,0 +1,29 @@
++++
+title = "Things I Learnt The Hard Way - Units Makes Things Clear"
+date = 2019-07-17
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "units", "explicit"]
++++
+
+You know what's one of the worst function names ever? `sleep()`.
+
+Sleep for how long? It is seconds or milliseconds?
+
+<!-- more -->
+
+Now let me ask you this: Would it clearer if the function was called
+`sleepForMs()`? Would you understand that the function would make the
+application sleep for a number of milliseconds?
+
+What about `sleepForSecs()`? Do you understand that this will force your
+application to sleep for a number of seconds?
+
+What if, instead of using the function name, you could use `sleep("10s")`? Does
+it make clear that you want it to sleep for 10 seconds?
+
+That's why adding units to the function or parameters make sense. It removes
+the ambiguity of what it means and doesn't rely on some specialized IDE/Editor
+that display the parameter names.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/optimization", prev_chapter_title="Optimization Is For Compilers", next_chapter_link="/books/things-i-learnt/config-file", next_chapter_title="The Config File Is Friend") }}