From 07a27c8fe62f6679465c11818eaa4b2a840ea9eb Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 17 Jul 2019 11:05:10 -0300 Subject: [PATCH] New chapter: Clear units --- content/books/things-i-learnt/_index.md | 1 + .../things-i-learnt/config-file/index.md | 2 +- .../things-i-learnt/optimization/index.md | 3 +- content/books/things-i-learnt/units/index.md | 29 +++++++++++++++++++ 4 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 content/books/things-i-learnt/units/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 18b6072..df8079a 100644 --- a/content/books/things-i-learnt/_index.md +++ b/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) diff --git a/content/books/things-i-learnt/config-file/index.md b/content/books/things-i-learnt/config-file/index.md index 692736a..f6884a8 100644 --- a/content/books/things-i-learnt/config-file/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/optimization/index.md b/content/books/things-i-learnt/optimization/index.md index 333e36a..576bb28 100644 --- a/content/books/things-i-learnt/optimization/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/units/index.md b/content/books/things-i-learnt/units/index.md new file mode 100644 index 0000000..9537884 --- /dev/null +++ b/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? + + + +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") }}