Code is communication

Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Martin Fowler, software author

I know the script is hard to read,
But reading's not the goal;
You're not supposed to understand —
That's why they call it code!

Just like music, poetry, or even language, code is a form of communication. Each line, each variable name, each class name etc. tells a story and gives context to the reader of the code.

Code has two purposes: to function and to communicate. Though your functional code does not have to communicate (i.e. it doesn't have to be readable), failing to do so may leave future developers (including you) puzzled at what you intended at the time of writing the code (i.e. if modifications ever need to be made).

First example

Take for instance, which is better?

This:

p = Point(True, 10, 10)

Or this:

p = Point(10, 20)

I think it is clear to see that the second block of code is slightly better than the first. Why? Because I can assume that 10 is the coordinate for the x axis and 20 is the coordinate for the y axis. That is all to it.

We could even make it more explicit:

p = Point(x=10, y=20)

This works too, but I would say either method would be preferred over the first.

So what's wrong with the first block of code?

The real problem is that we can't tell what the True argument is for. Thankfully, named arguments exist in Python¹:

p = Point(has_label=True, x=10, y=10)

However, this still feels worse. Why? A couple reasons:

• We would be unable to set x and y without setting has_label².
• It just doesn't look like every other Point object we may have encountered elsewhere. Why break convention if we don't have to?

I would argue a better constructor would be this (i.e. assuming that has_label must be used in the constructor):

p = Point(x=10, y=10, has_label=True)

At this point (pun intended 😉), it depends on how the user intends to make use of Point, but this is a lot less jarring than how it looked before.

In the old code, I would have to look up what the Boolean flag (True) represents; in the new code, its purpose is stated right in front of you. This may seem like a small change, but little changes like these really draw the line between amateur and professional developers.

Second example

Which is better?

This:

d = DateTime(2025, 8, 15, 13, 4, 20)

Or:

d = DateTime(Date(2025, 8, 15), Time(13, 4, 20))

Once again, I would say the second. There is nothing wrong with the first per se, but it's definitely harder to read compared to the second. Sometimes, there is no wrong or right answer; it's all contextual.

Bottom line

Every line of code tries to communicate to its reader, whether we like it or not. What story is your code telling?