Archive for February, 2023

I am doing it wrong

Take a deep breath, open up your mouth, and say it out loud in a full voice: “You are doing it wrong!”

You’ve done that before, right? I know I have. Once we know something (or think we do), it’s very easy to say someone is doing it wrong. Software developers do that. A lot.

  • “Wow, you’re using this library instead of that library? You’re doing it wrong!” 
  • “You’re using this pattern instead of that pattern? You’re doing it wrong!”,
  • “You’re writing a blog post instead of writing code…” You got the idea.

Once upon a time, I used to put comments in code everywhere. My current self could visit my past self and say “you’re doing it wrong!” about commenting code.

Whatever it is we’re doing “right” today is likely going to be “wrong” tomorrow, as long as we make the conscious effort to improve every day.

The person we’re interacting with today may be in the part of their journey that’s similar to our own a year ago. What looks “wrong” now, may be right, all things considered; writing comments for every line of code may be right for someone just getting started.

I’ve been avoiding videos, articles, and other types of content that try to grab us with:

  • You‘re doing it WRONG!”
  • “NEVER do this”
  • “ALWAYS do that”
  • “I have read all these books on –whatever-. Here is what YOU should ALWAYS do.”

I remember back as teenager when I learned how to play Black Sabbath’s Paranoid on the guitar. I played it for years thinking that was one of the easiest tunes ever. Until I find a video of Tony Iommi (the person who wrote the song!), talking about one tiny aspect that pretty much every guitar player gets wrong when playing that song: “they play the main riff off the 7th fret on the 5th string, instead of the 12th fret on the 6th string, where it sounds heavier…”

Growing up in Brazil, it took me years after I’ve moved to the US to finally hear I was pronouncing words such as pitch and peach exactly the same way (yup, the attentive reader can probably see how I could sound rude at times).

Far too often we won’t do something because of the fear of being wrong.

We don’t try a new language because we’re afraid of mispronouncing words.

We don’t try playing an instrument because we’re afraid it’ll sound bad.

I’ve heard Tim Ferriss suggest we ask 3 questions before offering an opinion. Now that is good advice. I also like Derek Sivers’s thoughts on “your first reaction is usually outdated“.

Hello there, future-me; do you think I’m doing it wrong right now? Be thankful that I am doing it; if I weren’t, that version of you would not exist.

“Always remember that to argue, and win, is to break down the reality of the person you are arguing against. It is painful to lose your reality, so be kind, even if you are right.” – Haruki Murakami

Let’s be kinder to ourselves and others.


Thoughts On Books: The Design of Everyday Things

This isn’t a book “review”; this is quick summary of what I got out of reading The Design of Every Things, by Don Normal. This content comes from what I’ve shared as a lightning talk for my fellow Improvers. I’ll keep referring to this book as DOET, for short.

Do I recommend this book?

Yes, I do. However, I’d recommend reading Kathy Sierra’s Badass: Making Users Awesome first; it helped me appreciate DOET more.

I have similar thoughts when comparing the canonical GoF book on Design Patterns to Head First Design Patterns; the former is a very dry read, although very comprehensive, whereas the latter is much easier to read (not coincidentally, Kathy is also involved in that one, and I really like that style of book).

DOET was originally published in 1988; the edition I’ve read is the “expanded and revised” one published in 2013. Even though some of the revised content may not resonate with younger readers, it did resonate with me.

Does it relate to software development?

As its title implies, the book is not about software development. However, it does mention some examples in software. But the way I see it is that it brings a shared vocabulary to design-related terms, much like design patterns do in software development.

Besides myself, two of my teammates participated in the book club, and we’ve been able to leverage the concepts learned in the book as we work in our project. Some concepts include:

  • Affordances
  • Signifiers
  • Constraints
  • Mapping
  • Feedback
  • Conceptual model

Here’s how I understand some of those concepts…


I think of it as a door to a building. That door is how I relate to the building; it’s how I can get in.


For whatever odd reason, this is the image that comes to mind when I think of signifiers:


For constraints, this is what comes to mind:

If you don’t get the reference, here’s a great 51-second video.

Contextual Model

As a hobbyist musician, I really appreciate how recording software models the experience we get in the real world.

For example, instead of showing me data entry forms to indicate how I want to my recorded guitar to sound, I get something that looks and behaves similarly to its counterpart in the real world.

As I move the microphone around on the screen, looking for a better positioning in front of the speakers, I hear the sound that reflects that setting, very similar to the experience in a real world studio.

To learn about those concepts, consider checking out Denny’s Improving Talk, Improving Software Design with Everyday Things, built on the lightning talk he shared with us at the end of the book club:

Human-Centered Design

Two points that resonated with me in the Human-Centered Design (HCD) section of the book:

  • Solving the right problem, doing so in a way that meets human needs and capabilities
  • Find the right problem, then find the right solution

I’ve recently shared my thoughts on approaching behavior-driven development without focusing on system behavior.

Most developers tend to immediately jump into their favorite technical solution, neglecting the needs and context of the humans who should benefit from it.

In the book, Norman says “I never solve the problem I am asked to solve“. I agree, and have been working hard for years trying to always separate the wants from the needs.

One of the examples in the book mentions a person walking in a store wanting to buy a drill bit. They don’t want a drill bit, they want a hole? Or do they? Their book library is growing, so they want new shelves. Would they consider trying ebooks instead? Do they want more books for their need to grow their knowledge through reading?

What have I been pondering?

There is a section later in the book that talks about humans and machines. Here are some thoughts that came from that…

Humans have been coaching other humans for a long time now. Even people at the top of their game have coaches.


The book good me thinking about the aspect of:

  • Humans coaching Machines, and
  • Machines coaching Humans


week human + machine + better process
superior to
strong human + machine + inferior process

Trying to think about that in the context of an accounting software:

novice accountant + computer + software with a built-in coaching process
superior to

seasoned accountant + computer + bad software

This next passage also got me thinking:

“Once technology can do our arithmetic, can remember for us, and can tell us how to behave, then we have no need to learn these things.”

Woah. Hold on. Technology telling us how to behave? So, what if we approach behavior-driven development with a spin of “the valuable desired behavior we’d like to coach humans into“? Food for thought.

I’ve enjoyed watching “The Future Of” Series on Netflix. The episodes on Gaming and Headphones are my favorites.

Best advice in the book

I’ve marked several passages in the book. This is my favorite one, which I come back to fairly often:

  • Do not blame people when they fail to use your products properly.
  • Take people’s difficulties as signifiers of where the product can be improved.
  • Eliminate all error messages. Instead, provide help and guidance.
  • Make it possible to correct problems directly from help and guidance messages. Allow people to continue with their task: Don’t impede progress. Never make people start over.
  • Assume that what people have done is partially correct. If it is inappropriate, provide the guidance that allows them to correct the problem and be on their way.

For more…

If you crave for more, look up Don Norman’s videos on YouTube; there are some great ones out there.

And there’s also this one by yours truly!

Leave a comment

Optimize code for reading, not debugging

I see a lot of code that includes variables not used for anything:

The variable inside of that method does not add anything to improve the understanding of the code. That’s normally done to make debugging easier, when setting a breakpoint and hovering over the variable to inspect it:

That way, the developer can set a breakpoint, and hover over the variable to inspect it.

Instead of doing that, I’d rather have that method written like this:

When I need to debug that method and inspect what it returns, I use the shortcut to *introduce a variable*, do my debugging, and then either undo the change or hit the shortcut to *inline the variable* (most IDEs support such refactoring. Even if the one I’m using doesn’t, creating a variable named *x* or *temp* should take no time).

Some IDEs, such as Rider, even show a method’s return in the debugger without the need for a variable, as seen below:

Summing up:

  • Optimize the code for reading
  • Get familiar with your IDE’s debugging capabilities
  • Change the code to facilitate debugging when needed
  • Change the code back for optimized reading before committing it

Leave a comment

BDD: What if we do NOT focus on ‘System’ behavior?

This is a way many people and literature talk about Behavior-Driven Development (BDD): “it encourages teams to use conversation and concrete examples to formalize a shared understanding of how the application should behave.” (wikipedia)

Focus on the application‘s behavior leads to user stories that start like this:

As a system…

Do we write code for the system?
Are we serving the system?
Is the system a stakeholder?

Continuing the story…

I want to…

Oh, so the system tells us what it wants? Are we already there?

Most software developers have a strong tendency to jump too quickly into problem-solving from a technical perspective, failing to see the problems the humans need solving.

Say we’re using state-of-the-art technology, implemented with the most amazing code, on the most advanced platforms, using valuable resources, such as time, attention, and money; it it worth it if humans’ lives aren’t any better?

Many times, the problem that needs solving is a process problem. Many times, it’s a people problem. Often times, social and/or cultural problems also get in the mix. Here’s an example of the latter:

A socio-cultural problem

In the mid 2000s, I met a group of developers in Redmond who had just come back from Sao Paulo, Brazil.

They had been working on a pilot project to improve the quality of public transportation, implementing a tracking system for the buses, so people could know with more accuracy when their next ride would show up.

The system was working great, except for this one bus that kept “disappearing” from the system for at least 30 minutes everyday. Puzzled, they developers were looking at the data, code, and everything in between.

The cause of the problem?

The bus driver found out how the system worked and figured out he could use its sim card in his own phone to make long distance calls to his family, who lived in the north part of the country. That was a time when long distance calls were still very expensive.

Most local developers would have caught that possibility that the foreign ones didn’t consider. The system was behaving according to spec. But the humans…

Maybe the problem that needs solving is dealing with some people’s natural behavior that may put them far from a bigger goal.

Maybe we’re trying to develop a solution that will acknowledge people’s natural behavior and make sure the desired outcome is achieved.

Or maybe the solution can help change people’s behavior gradually.

Here’s an example. In 2017, I started riding sport bikes (motorcycles, that is) at race tracks. It didn’t take much to realize that it can be an expensive sport. Doing my research and asking other riders how much they spend in their riding season, some would say “I don’t even wanna know!” Asking how often they ride, some would answer “whenever money permits“.

Well, I do want to know; if I know and understand where the money goes, I can identify ways to optimize my expenses and get to ride more!

Here’s one of the user stories I wrote at the time to capture that need (which I implemented in and have been using all these years):

Estimating Costs

In order to plan out a track day calendar within my budget
As a rider
I want to indicate estimated costs for each track day

Scenarios for the story looked something like this:

Given track days I plan on attending
When I enter their estimated costs
Then I can see the budget I will need for my riding season

By facilitating a behavior of setting proper budget for goals that are important to me, my life is better. My behavior. Not the system’s behavior.

How did that work out for me in that specific case?

Comparing my Year #1 in track day riding to Year #6, the number of days I rode went up by 146%, while the money I’ve spent on it went down by 78%. Value up, cost down. Win-win in my book. The chart below shows 2017 through 2022.

The closer we get to the bits and bytes, yes, specs will tend to describe what we expect from the system. But that’s NOT where I believe we should start from.

In the great books Specification by Example and Writing Great Specifications, the authors are very specific at sticking to the definition of BDD as Dan North meant it.

In this post, I’ve put my own spin on it, as this is how I’ve practiced it over the years.

In his talk about “Leadership vs Management: What it means to make a difference”, Seth Godin talks about how people think Beethoven’s 5th Symphony should sound: the way the maestro wrote it, or the way made popular by Arturo Toscanini? Interesting watch.


Leave a comment