From b5b20d67efe1e2befe966a9f6bb406ad09539806 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 31 Jul 2019 12:29:54 -0300 Subject: [PATCH 1/3] New chapter: Bad code defense --- content/books/things-i-learnt/_index.md | 1 + .../things-i-learnt/bad-code-defense/index.md | 29 +++++++++++++++++++ .../things-i-learnt/own-your-shit/index.md | 2 +- 3 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 content/books/things-i-learnt/bad-code-defense/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index ae1f75e..01ea70e 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -98,3 +98,4 @@ template = "section-contentless.html" * [Keep A List of Things I Don't Know](things-i-dont-know) * [You Always Have The Time](time) * [Own Your Shit](own-your-shit) + * [Don't Defend Bad Code](bad-code-defense) diff --git a/content/books/things-i-learnt/bad-code-defense/index.md b/content/books/things-i-learnt/bad-code-defense/index.md new file mode 100644 index 0000000..a506f0f --- /dev/null +++ b/content/books/things-i-learnt/bad-code-defense/index.md @@ -0,0 +1,29 @@ ++++ +title = "Things I Learnt The Hard Way - Don't Defend Bad Code" +date = 2019-07-31 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "personal", "bad code", "defend"] ++++ + +Bad code exists everywhere. You shouldn't defend it, even if it is your own +code. + + + +Bad code isn't bad on purpose. It sadly happens. But because it is bad, you +shouldn't defend it. + +For example, an application does whatever you need. But it crashes from time +to time. Software shouldn't crash and you shouldn't defend it just because it +does whatever you need. + +Your internal application works on a single browser. That's bad. "But maybe +the other devs thought it wouldn't be worth working on all browsers". No. It +is _bad_. You shouldn't defend the other devs because they decided to focus on +a single browser due whatever problems they were facing. Sure it wasn't nice +that they had to do this trade-off, but it is still _bad_ software. + +If we keep defending this kind of software, we will still get bad software. + +{{ chapters(prev_chapter_link="/books/things-i-learnt/own-your-shit", prev_chapter_title="Own Your Shit") }} diff --git a/content/books/things-i-learnt/own-your-shit/index.md b/content/books/things-i-learnt/own-your-shit/index.md index 469e229..4665078 100644 --- a/content/books/things-i-learnt/own-your-shit/index.md +++ b/content/books/things-i-learnt/own-your-shit/index.md @@ -43,4 +43,4 @@ can't simply move my mistake to some other personality; who was wrong was _me_. And unless I own my shit up, I'd never get the understanding I'd need to see my mistake about Scala in the first place. -{{ chapters(prev_chapter_link="/books/things-i-learnt/time", prev_chapter_title="You Always Have The Time") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/time", prev_chapter_title="You Always Have The Time", next_chapter_link="/books/things-i-learnt/bad-code-defense", next_chapter_title="Don't Defend Bad Code") }} From 9b3b548e1e7c4b290b088b4e4b0f9e441b8ce34e Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 31 Jul 2019 12:45:04 -0300 Subject: [PATCH 2/3] New chapter: team discussions --- content/books/things-i-learnt/_index.md | 1 + .../things-i-learnt/hero-projects/index.md | 2 +- .../things-i-learnt/specialists/index.md | 2 +- .../things-i-learnt/team-discussion/index.md | 42 +++++++++++++++++++ 4 files changed, 45 insertions(+), 2 deletions(-) create mode 100644 content/books/things-i-learnt/team-discussion/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 01ea70e..3dd7cde 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -76,6 +76,7 @@ template = "section-contentless.html" * [Code Style: Follow It](code-style) * [... Unless That Code Style Is The Google Code Style](google-code-style) * [Hero Projects: You'll Have To Do It Yourself](hero-projects) + * [Global Changes Must Be Discussed With The Whole Team First](team-discussion) * Personal * [Companies Look For Specialists But Keep Generalists Longer](specialists) * [Keep A List of Stupid Bugs That Took More Than 1 Hour To Solve](stupid-bugs-list) diff --git a/content/books/things-i-learnt/hero-projects/index.md b/content/books/things-i-learnt/hero-projects/index.md index ec631bd..4f7bf44 100644 --- a/content/books/things-i-learnt/hero-projects/index.md +++ b/content/books/things-i-learnt/hero-projects/index.md @@ -28,4 +28,4 @@ Just to be clear: Sometimes an hero project will fail [because the answer is obvious](/books/things-i-learnt/right-tool-obvious). Don't let that make you feel down. -{{ chapters(prev_chapter_link="/books/things-i-learnt/google-code-style", prev_chapter_title="... Unless That Code Style Is The Google Code Style", next_chapter_link="/books/things-i-learnt/specialists", next_chapter_title="Companies Look For Specialists But Keep Generalists Longer") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/google-code-style", prev_chapter_title="... Unless That Code Style Is The Google Code Style", next_chapter_link="/books/things-i-learnt/team-discussion", next_chapter_title="Global Changes Must Be Discussed With The Whole Team First") }} diff --git a/content/books/things-i-learnt/specialists/index.md b/content/books/things-i-learnt/specialists/index.md index 843edcf..829e483 100644 --- a/content/books/things-i-learnt/specialists/index.md +++ b/content/books/things-i-learnt/specialists/index.md @@ -40,4 +40,4 @@ in C show up and guess who also knew C? [^1]: ... which led me into some sad times when I was working with Python. -{{ chapters(prev_chapter_link="/books/things-i-learnt/hero-projects", prev_chapter_title="Hero Projects: You'll Have To Do It Yourself", next_chapter_link="/books/things-i-learnt/stupid-bugs-list", next_chapter_title="Keep A List of Stupid Bugs That Took More Than 1 Hour To Solve") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/team-discussion", prev_chapter_title="Global Changes Must Be Discussed With The Whole Team First", next_chapter_link="/books/things-i-learnt/stupid-bugs-list", next_chapter_title="Keep A List of Stupid Bugs That Took More Than 1 Hour To Solve") }} diff --git a/content/books/things-i-learnt/team-discussion/index.md b/content/books/things-i-learnt/team-discussion/index.md new file mode 100644 index 0000000..652eb77 --- /dev/null +++ b/content/books/things-i-learnt/team-discussion/index.md @@ -0,0 +1,42 @@ ++++ +title = "Things I Learnt The Hard Way - Global Changes Must Be Discussed With The Whole Team First" +date = 2019-07-31 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "team", "changes"] ++++ + +So you got tired of bad tests and decided it is a good idea to add some [fuzz +testing](https://en.wikipedia.org/wiki/Fuzzing) tool. Before you do add it in +the main branch, you _have_ to discuss it with your team. + + + +It's mind-bogging that some people think something it's so good that they +don't need to discuss with the whole team about it; they simply do. They don't +seem to care that people have their workflows and changing something would +break them. But hey, I've seen it so many times it is not even fun. + +And let me clear here: You need to discuss it with the _whole_ team, not just +some of it (excluding people on vacations, 'cause you don't want to call them +just to tell them something will change). Worse: Don't discuss only with those +that will agree with you; you may not have seen all the problems those changes +will inflict on the other devs workflows but, by bringing that with those that +may not agree with you, you may gain some more insights on what could go +wrong. + +Also, focus on what would be the gains and the loses. "We'll get better tests, +but you'll have to take a bit more care on the way you write tests" is a good +explanation, specially if you show the changes people will have to do in +future tests. Also also, notice that I said _future_ tests: if you want to +implement something new, you _must_ be sure it won't require everyone getting +out of their way to make your idea work -- don't make people rewrite tests +'cause they will break; don't make the other devs reformat their code 'cause +you decided, alone, to add a linter to your CI with your own rules; don't make +people worry about unwritten tests 'cause you decided it would be a good idea +to add a code formatting tool and that would make your coverage tool think +they are changing some unrelated piece of code that wasn't untested before. + +Don't be a jerk thinking you know more than your whole team. + +{{ chapters(prev_chapter_link="/books/things-i-learnt/hero-projects", prev_chapter_title="Global Changes Must Be Discussed With The Whole Team First", next_chapter_link="/books/things-i-learnt/specialists", next_chapter_title="Companies Look For Specialists But Keep Generalists Longer") }} From 906ee3f9155a25cde9dca1ae25f9852d8a40b08b Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 31 Jul 2019 13:25:08 -0300 Subject: [PATCH 3/3] New chapter: be transparent --- content/books/things-i-learnt/_index.md | 1 + .../things-i-learnt/add-then-remove/index.md | 2 +- .../books/things-i-learnt/log-events/index.md | 2 +- .../things-i-learnt/transparent/index.md | 30 +++++++++++++++++++ 4 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 content/books/things-i-learnt/transparent/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 3dd7cde..3231340 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -64,6 +64,7 @@ template = "section-contentless.html" * [Not Just Function Composition, But Application Composition](application-composition) * [Even for Application Composition, Start Stupid](app-composition-stupid) * [Logs Are For Events, Not User Interface](log-events) + * [Be Transparent With The User](transparent) * [One Version To Add, One Version To Remove](add-then-remove) * [Learn To Monitor](monitoring) * Community/Teams diff --git a/content/books/things-i-learnt/add-then-remove/index.md b/content/books/things-i-learnt/add-then-remove/index.md index 936d6cb..bb088c7 100644 --- a/content/books/things-i-learnt/add-then-remove/index.md +++ b/content/books/things-i-learnt/add-then-remove/index.md @@ -30,4 +30,4 @@ deployed _at the same time_ as the new interface; by adding the new link format in another field, we can deploy the backend easily without breaking the current system. -{{ 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/monitoring", next_chapter_title="Learn To Monitor") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/transparent", prev_chapter_title="Be Transparent With The User", next_chapter_link="/books/things-i-learnt/monitoring", next_chapter_title="Learn To Monitor") }} diff --git a/content/books/things-i-learnt/log-events/index.md b/content/books/things-i-learnt/log-events/index.md index 834e018..59b21cc 100644 --- a/content/books/things-i-learnt/log-events/index.md +++ b/content/books/things-i-learnt/log-events/index.md @@ -43,4 +43,4 @@ 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/app-composition-stupid", prev_chapter_title="Even for Application Composition, Start Stupid", next_chapter_link="/books/things-i-learnt/add-then-remove", next_chapter_title="One Version To Add, One Version To Remove") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/app-composition-stupid", prev_chapter_title="Even for Application Composition, Start Stupid", next_chapter_link="/books/things-i-learnt/transparent", next_chapter_title="Be Transparent With The User") }} diff --git a/content/books/things-i-learnt/transparent/index.md b/content/books/things-i-learnt/transparent/index.md new file mode 100644 index 0000000..b40aa80 --- /dev/null +++ b/content/books/things-i-learnt/transparent/index.md @@ -0,0 +1,30 @@ ++++ +title = "Things I Learnt The Hard Way - Be Transparent With The User" +date = 2019-07-31 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "ux", "ui"] ++++ + +Since we are talking about [logging](/books/things-i-learnt/log-events), +another thing you must do is to be transparent with the user in your user +interface. + + + +And by "be transparent", I meant that your website/mobile app needs to point +out to the user that the webserver is down instead of saying to the user to +check their internet connection; your application _is_ getting something from +the webserver, so you _can_ say "Oops, something wrong on our side". + +Another example: If you need to check a bunch of data before saying "It's +done", add a counter to show the user that the application is doing something. +[Joplin](https://joplinapp.org/), when syncing data with a webdav server, +needs to check a bunch of files; one version would simply sit still with a +spinner on "Syncing" and nothing more; when they added a counter, I could +easily see that there was something going on. + +Those small details, for as bad as they may make you look, will win points +with the user in the long run. + +{{ 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/add-then-remove", next_chapter_title="One Version To Add, One Version To Remove") }}