Code Quality on MoskitoHero

Love your error messages as thyself

Tue, 17 May 2022 07:44:36 +0000

Learn to hate, then love error messages.

Stack Overflow overflow

I have lost so much time on Stack Overflow.

I mean Stack Overflow is great, and software development knowledge would not be so advanced and so widespread without its great influence. What I mean is that I have often found myself repeating the endless pattern of 'Hey, I have an error… Wow, so many words… Let’s google this. Stack Overflow has it! Let’s see what they say'

I am not talking about the infamous Stack Overflow copy-paste syndrome, nor am I dismissing the great answers produced by the great developers out ther, but rather about the missing step in the example above: making sense of the error message myself before actually looking for a ready-made answer.

Our brain is so quick at taking shortcuts that it often makes us lazy and skip the seemingly unneeded steps our thinking needs to fully develop. Take the example of walking. Although I don’t exactly remember taking my first step in this world, I can imagine it was a movement that required so much concentration - not to say bravery - and coordination that it must have felt quite awkward at the beginning. Today, I don’t even think about it. My brain just orchestrates everything, allowing me to go for a walk and actually think about something else.

Think about the first day you typed your first computer program. Think about the way you were thinking at the time. Maybe you are currently learning computer science and many mechanisms experienced developers don’t even think about are steps you consciously take, one by one, in order to reach code quality - or even to write code that actually works.

And while learning, we all encountered bugs. The language we were coding in was talking to us with complicated words, and concepts we sometimes did not even know about. We all googled for solutions. And Stack Overflow is so well conceived and maintained that we most certainly found the answer there. And it happened again. Error messages were so hard to understand, so cryptic, sometimes. So we just kept copy-pasting the error messages, and it just kept throwing correct answers at you, which, with a little adaptation, just worked.

And then, your brain skipped the error-message-reading step.

But we don’t want to just be very, very, very talented googlers, do we?

RTFEM!

Read the f***ing error messages!

So I encourage all of you learners to actually take a long look at the error messages that are thrown right in your face just as you were expecting a successful compilation. Take the time to read them. Take the time to look at those weird symbols that show up here and there. And you know what? You may not get to the point quicker at first, but you will gain a deeper knowledge of how your language is actually built, how it works internally. You might look at your fellow programmers increase their skills faster on the surface, but your understanding of error messages will eventually turn you into a Code Jedi Master.

What made me really stop overlooking error messages was reading Ruby Under A Microscope by Pat Shaughnessy, a most excellent book about the way Ruby is actually written in C, the way the language parser works and the way it turns the words you write into machine-understandable concepts.

Somewhere in the first part of the book that introduces how the parser works, the author talks about language tokenisation, which is - very basically - how the parser takes words and understand how to match them with a feature. And here they were, in a code example, my long-seen-yet-so-little-known error message friends, namely tSTRING, tCONSTANT and tINTEGER.

If only I had known what these correspond to before, error messages such as these would never have had me google for an answer.

But how could I know? When you google for ruby tString, you get all sorts of results, mostly skipping the preceding t. In order to get to the real stuff, I should have taken the time to actually read the error messages and wonder:

What is the language trying to tell me?

And if that sounds awkward, just remember that your programming language is actually a computer program written by other humans, and ask yourself:

What is the author of the language telling me to look at?

Chances are he is trying to get you to look at features of the language that may not be plain to see, but a little hidden from sight. And if he is trying to have you look at these, you might just as well do it. And learn.

Learn to love your error messages

Not only should you read error messages carefully, but you should also take the time to craft yours with love and care. Like I said in an earlier post, you should always try to write code with your future self in mind. And I guess the same applies to error messages.

Don’t just raise Error, or StandardError in your lib. Actually write your own OddError class. Give it a message. Make it clear. Make it so your user - and that may be the future you - is eager to look at what you coded and understand how it is architectured.

An error message must be clear, so it requires your code to be clear, and therefore it requires your programming mind to be clear about what the code is actually doing. Error messages tell something about your self.

Error messages are the conversation between the author of a program and his users. As a programmer, you will be either one or the other, in turn, and often both at the same time.

Error messages will make you grow while learning software. They will make you grow while using software. They will make you grow while writing software. Do not just dismiss them and skip to the Stack Overflow step.

Writing code for your future self

Sun, 21 Nov 2021 07:44:36 +0000

We all write bad code. Let’s face it. Even if we do our best at writing the most efficient and well-designed code, we all happen to write this dirty method we don’t feel so proud of and dread having to debug next month, or next year.

I’m not going to talk about that code, because it’s so easy to spot and there is no need to write blog posts about it. What I’m interested in is code which looks fine when you have finished typing, but will bite you in the back someday. It ends up being hard to maintain, extend or even understand. After years of coding, I have come up with a set of warnings that alert me whenever I am heading for a dead end.

Meaning

Code is language. Even more so when you use a programming language such as Ruby, which is designed to be very expressive. But to me, code begins to smell when it becomes unclear what it really does.

Names

Naming is essential. One of the thing that changes the most in my creation process is probably the name of the classes, methods and variables I design.

Humans name things they understand. And the higher the knowledge of an element, the sharper the naming. Renaming my classes in the development process is usually a good sign that I am getting a better idea of what they do or what concept they stand for.

Method length

One of the most frequent design patterns we are taught as aspiring OOP developers is to keep methods shorter than a few lines. One caveat, however, is that code ends up scattered all over the place, and you can sometimes lose touch with the lifecycle of your data. This is especially true for classes that are used to build a data structure.

For instance, take this class that builds a data hash to be sent to FCM:

module MobilePush
  class FcmNotification < BaseNotification

    def launch
      # Bootstrap stuff...
      push_service.send_message(project, data)
    end
    private
      # Lots of methods...
      def data
       {
          notification: json_notification,
          recipient: recipient_name,
          room: room_name
        }
      end
      # Lots of other methods...
      def json_notification
        @notification.to_json
      end
      def recipient_name
        @recipient.name
      end

      # Maybe a few other methods...
      def room_name
        @room.name
      end
      # The rest of the methods...
  end
end

Note: This example is a little over-simplified for brevity. But you get the idea.

I wrote this thinking "Hey that’s smart! Everything is nicely sorted. It really looks like clean code".

Then I took a few day’s break with my family. While I was away, one of my co-workers had to deal with my new code and add a new feature. But he found it unnecessarily abstracted, hard to maintain and extend. And he was right. So I refactored it to:

module MobilePush
  class FcmNotification < BaseNotification

    def launch
      # Bootstrap stuff...
      push_service.send_message(project, data)
    end
    private
      # Lots of methods...
      def data
       {
          notification: @notification.to_json,
          recipient: @recipient.name,
          room: @room.name
        }
      end
      # The rest of the methods...
  end
end

So OK, I had to swap out room_name for @room.name in two or three places in the class, because it was also used elsewhere. But I also made my code a little less abstracted. Now, my co-worker knows exactly what data is made of, at a glance.

Stories

One thing to remember when writing code, is that it is not just meant to be effective and concise. Code is meant to be read by others. Your co-workers, your team leader, and even more crucially, by the person who will be in charge of your once-new, now-legacy codebase.

One-liners

I love one-liners. They are fun, straight to the point, and they showcase the technical skills and the wit of their creators. They are to programming what punchlines, or newspaper headlines are to writing. But who wants to read a whole book written in this way?

Even though I sometimes use one-liners in my code, I only do so when I feel confident my successor - or my future self - will be able to make sense out of it easily.

Be explicit

I believe that most code should be explicit and guide the reader with landmarks that will help him or her follow along.

For instance, instead of this kind of expression:

Device.where('last_seen > ?', 1.hour.ago).where(logging: true).where(notifications: true).last.send_message(topic, payload)

I would rather either use class methods, or scopes in the model, to end up with:

device = Device.active_last(1.hour).logging.notifying.last
device.send_message(topic, payload)

I’m not stupid. I can understand the first example. But when parsing hundreds of lines of code to find a bug, I can look at this code and instantly tell what it does. No need to make sure I got the < and the > right. This was done once, on the day it was typed, and I can rely on it with confidence because each of these methods is tested and does what it says.

Be methodic

I like to separate intents in what I do with my class. When you tell a story, you first introduce your character with a clear description. Then only you give him an active role in your story. That’s what the code example above is doing. I could also have easily written:

Device.active_last(1.hour).logging.notifying.last.send_message(topic, payload)

But that’s mixing intents. This line is both querying the model and triggering an action, so you start reading the line thinking: "Oh, he is defining the Device" and finish it thinking "Ah. No, he is sending this device a message". Your reader should never ever be misguided, even in short, simple assertions like these.

I try to separate queries from actions. They are two types of tasks and require two distinct steps in my code.

Consider these three sentences:

The man in the bar that is old and dirty is talking about yesterday’s soccer results. - messy

There is a man who is talking in the dirty old bar about yesterday’s soccer results. - clearer

In the dirty old bar, there is a man. He is talking about yesterday’s soccer results. - crystal clear

I want my code to be crystal-clear. I want my code reviewer, my successor or my future very-tired-on-a-friday-afternoon self to perfectly get what I am doing with my code.

Tests

Writing tests helps me identify dependencies. Integration tests often require quite a lot of bootstrapping: a logged in user, a few related entities… that’s fine.

But I sometimes write tests that rely too much on other models. If you can’t test your Comment model without a Post model, then something may be too tightly coupled in the code, and the relationship between those entities needs to be inquired.

Assertions also guide me towards code clarity. I have found that when I have trouble defining an expectation in my test, it usually means that this particular method is not doing something clear enough. It either needs to be split into smaller methods or completely re-thought about.

A word about comments

Another sign that code needs to be refactored is comments. Comments mostly indicate that what the program does is unclear. So when I see comments in code, the first thing I do is delete them and figure out what is happening without reading them. And whenever that comes out messy, it’s a good sign that they can all be replaced by a single TODO: refactor.

Comments are also often a sign of an external dependency. Typically, you will get this kind of thing:

# Handle temperature > 21
# Deal with legacy customer IDs

The first one might depend on the device you’re dealing with, and that dependency might be addressed by the hardware team.

The second one could be deleted by resorting to an inherited class, like LegacyCustomer, which could handle that kind of special user cases and keep the Customer class clean with a predictable and simple interface.

The only comments I keep are top comments above class declarations, Yard documentation, a few refactor TODOs and silly, fun meta about the code.

Conclusion

I sometimes look at messy code and wonder "who wrote this piece of crap?"

Let’s see… Git blame…

Me.

I don’t like this feeling. I want to feel proud of my code. I want other developers, including my future self, to make sense out of it easily and instantly, and thank me for making the effort of crafting code that makes sense, is easy to debug and maintain.

Following this set of guidelines will hopefully help me down that path.