From 6989f28cdb29ffcee6df79f678c15b8603afd583 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Mon, 1 Jul 2019 19:41:40 -0300 Subject: [PATCH 1/2] New Chapter: Start Stupid --- content/books/things-i-learnt/_index.md | 1 + .../languages-are-more/index.md | 2 +- .../things-i-learnt/start-stupid/index.md | 33 +++++++++++++++++++ .../books/things-i-learnt/use-utf8/index.md | 2 +- 4 files changed, 36 insertions(+), 2 deletions(-) create mode 100644 content/books/things-i-learnt/start-stupid/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index bda025c..927de42 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -41,6 +41,7 @@ template = "section-contentless.html" * [Resist The Temptation Of Easy](resist-easy) * [Always Use Timezones With Your Dates](use-timezones) * [Always Use UTF-8 For Your Strings](use-utf8) + * [Start Stupid](start-stupid) * Community/Teams * [A Language Is Much More Than A Language](languages-are-more) * [Understand And Stay Away From Cargo Cult](cargo-cult) diff --git a/content/books/things-i-learnt/languages-are-more/index.md b/content/books/things-i-learnt/languages-are-more/index.md index c0ac487..9e4dbea 100644 --- a/content/books/things-i-learnt/languages-are-more/index.md +++ b/content/books/things-i-learnt/languages-are-more/index.md @@ -39,4 +39,4 @@ surface of what the whole of a language encapsulates and if you ignore the other elements in it, you may find yourself with a cute language in a community that is always fighting and never going forward. -{{ 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/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} diff --git a/content/books/things-i-learnt/start-stupid/index.md b/content/books/things-i-learnt/start-stupid/index.md new file mode 100644 index 0000000..64e1ef9 --- /dev/null +++ b/content/books/things-i-learnt/start-stupid/index.md @@ -0,0 +1,33 @@ ++++ +title = "Things I Learnt The Hard Way - Start Stupid" +date = 2019-07-01 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "kiss"] ++++ + +One way to get away from the IDE is to "start stupid": Just get the compiler +and get an editor (ANY editor) with code highlight and do your thing: Code, +build it, run it. + + + +Notice that say "stupid way", not "simple way". + +Doing things in the stupid way is not the easiest way to start a project. How +could one beat the easy of clicking a button and having the whole structure of +a project done for you? + +But starting it in the stupid way, in which you have to think your project +layout, how to build stuff, how to run tests, how to do _everything_ may give +you some insights on how things work, how the pieces mesh together and how to +cogs turn around. + +Honestly, you don't have to do this with all projects. You can still use your +favourite IDE and do things in the easy way. But you can also have that side +project on which you'll do everything in the stupid way, just to understand +what your IDE is doing. + +And when you grasp that, you'll be able to use _any_ IDE. + +{{ 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/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} diff --git a/content/books/things-i-learnt/use-utf8/index.md b/content/books/things-i-learnt/use-utf8/index.md index ef47acc..840162c 100644 --- a/content/books/things-i-learnt/use-utf8/index.md +++ b/content/books/things-i-learnt/use-utf8/index.md @@ -52,4 +52,4 @@ single character. Walking through the whole string would require traversing the string character by character, instead of simply jumping straight to the proper position. But that's a price worth paying, in the long run. -{{ chapters(prev_chapter_link="/books/things-i-learnt/use-timezones", prev_chapter_title="Always Use Timezones With Your Dates", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/use-timezones", prev_chapter_title="Always Use Timezones With Your Dates", next_chapter_link="/books/things-i-learnt/start-stupid", next_chapter_title="Start Stupid") }} From 9bbd3fb16d37298650c35fe25327fe06ec44ab2c Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Mon, 1 Jul 2019 19:55:51 -0300 Subject: [PATCH 2/2] New chapter: Logs for events --- content/books/things-i-learnt/_index.md | 1 + .../languages-are-more/index.md | 2 +- .../books/things-i-learnt/log-events/index.md | 44 +++++++++++++++++++ .../things-i-learnt/start-stupid/index.md | 2 +- 4 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 content/books/things-i-learnt/log-events/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 927de42..3190069 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -42,6 +42,7 @@ template = "section-contentless.html" * [Always Use Timezones With Your Dates](use-timezones) * [Always Use UTF-8 For Your Strings](use-utf8) * [Start Stupid](start-stupid) + * [Logs Are For Events, Not User Interface](log-events) * Community/Teams * [A Language Is Much More Than A Language](languages-are-more) * [Understand And Stay Away From Cargo Cult](cargo-cult) diff --git a/content/books/things-i-learnt/languages-are-more/index.md b/content/books/things-i-learnt/languages-are-more/index.md index 9e4dbea..827bc93 100644 --- a/content/books/things-i-learnt/languages-are-more/index.md +++ b/content/books/things-i-learnt/languages-are-more/index.md @@ -39,4 +39,4 @@ surface of what the whole of a language encapsulates and if you ignore the other elements in it, you may find yourself with a cute language in a community that is always fighting and never going forward. -{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/log-events", prev_chapter_title="Logs Are For Events, Not User Interface", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} diff --git a/content/books/things-i-learnt/log-events/index.md b/content/books/things-i-learnt/log-events/index.md new file mode 100644 index 0000000..311fc95 --- /dev/null +++ b/content/books/things-i-learnt/log-events/index.md @@ -0,0 +1,44 @@ ++++ +title = "Things I Learnt The Hard Way - Logs Are For Events, Not User Interface" +date = 2019-07-01 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "logs", "ui"] ++++ + +Two things in one: First of all, when using logging, use it to log events, not +for user interfaces; second, log _events_ in a machine readable way, not +necessarily an human readable format. + + + +For a long time, I used logs to show to the user what was happening. Nothing +could be the idea of displaying errors, general information and, if the user +requested, the internals of whatever is going on in one simple way. I mean, +yeah, let me add the errors, the info messages and the debug messages and let +the user decide what they want to see. + +But that's not what logs are targeted for -- and now I'm having to rethink +most of the stuff I already wrote. + +Use the standard output to inform the user what's going on, in a human +readable format; use the standard err to inform the user when things go wrong; +but use the logs to capture something that you'll have to process later, so +you should probably use a format that it is easier to parse, even if it is not +so friendly. + +As an example, let's say you're connecting to a server. You could use the +standard output to say "Connecting to server", to give the user a feedback +about what's going on; at the same time, you could log "CONNECTION +[SERVER]", with the IP/Name of the server you're connecting. Surely, the +"CONNECTION" word is not that friendly to the user, but if you had to parse +the line, it would be really easy, wouldn't it? + +Another example: If your application is adding a record to the database, there +is nothing wrong logging "ADDING_RECORD: field=value; field=value; +field=value" 'cause, in case something goes wrong while saving the record, you +could have the values to try to figure out why it failed -- surely, logging +why it failed also helps, but you know what I mean. This is an example of +something that makes complete sense in logs, but not in user interfaces. + +{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} diff --git a/content/books/things-i-learnt/start-stupid/index.md b/content/books/things-i-learnt/start-stupid/index.md index 64e1ef9..ade4987 100644 --- a/content/books/things-i-learnt/start-stupid/index.md +++ b/content/books/things-i-learnt/start-stupid/index.md @@ -30,4 +30,4 @@ what your IDE is doing. And when you grasp that, you'll be able to use _any_ IDE. -{{ 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/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} +{{ 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/log-events", next_chapter_title="Logs Are For Events, Not User Interface") }}