Code Whispering: How Talking to Myself Makes Me a Better Developer

Intro

Let's imagine: you are developing a new feature for your app. The feature should already work in your understanding, but it doesn't. You are modifying code here and there, but it doesn't work as expected. Hours pass by. It doesn't feel right; something is wrong. Sound familiar? In this blog post, I reveal a powerful technique that can dramatically improve your code reading awareness - a powerful technique that can save you countless hours of debugging.

First of all, I am not an expert on the staff I write about in this blog post. I learn, and I write here what I discovered.

Three Levels of Reading Code Awareness

I think there are three levels of reading code awareness. The first level we can call "Cursory examination". This is when you read code without giving it enough attention. You do not have any internal talking or active thinking. Your mind drifts somewhere more often. It may be more unconscious than conscious. You are making quick assumptions, skimming through lines, and as a result, you are more likely to miss bugs that could cause significant issues down the road. This may be the default choice when it comes to reading code. But it is really inefficient and wastes hours.

The second level we can call "Inner dialog". There you are actively talking in your mind about your code, actively asking questions, explaining what part of the code does what, and paying more attention to the code. You are not talking aloud; you are silent on the outside and actively thinking inside. By asking questions, you may realize that actually, the code works differently than you expected. This level requires exerting some mental effort to maintain. And this is a good place if you can maintain that. But what may happen is that your mind may drift away, and therefore, you may end up paying less attention and having a worse understanding of the code.

The third level we can call "Deliberate code articulation". There, you have a high level of awareness. You actually start thinking aloud when reading code. This way, you are paying more attention, and your mind is less likely to drift away, as it may happen when you are talking only in your mind. It is similar to the second level, but as you can see, it is more stable and reliable because of the amount of attention you are paying. It takes more distractions to start thinking about something else when you are actively engaged in a discussion with yourself. And, as a result, you are able to finish the feature for the app more quickly.

What You Can Do

I think it is a good idea to start vocalizing your thoughts, or in other words, talking to yourself when reading code. Your awareness raises, fewer bugs are coming your way, and you are happier with your code and, as a result, your app. Here is an example of how you can do that:

function processPayment(user, amount) {
  // Vocalized thought: If there is no user or the user is not verified, then we log an error to the console and return null
  if (!user || !user.isVerified) {
    console.error("Unverified user");
    return null;
  }

  // Vocalized thought: If the type of the amount variable is not a number or the amount is less than or equal to zero, we log the error to the console and return null
  if (typeof amount !== "number" || amount <= 0) {
    console.error("Invalid amount");
    return null;
  }

  // Vocalized thought: We return an object where we have an id that is constructed by using Math.random(), which is converted to a string using base-36 encoding, and on this we use a slice method to take only characters from 2 to 11. We also have a user property that contains a name taken from the user object, the amount property with the value that was passed to the function, and the timeStamp property that was created using the new Date() function, which returns a date object as a result.
  return {
    id: Math.random().toString(36).slice(2, 11),
    user: user.name,
    amount: amount,
    timestamp: new Date(),
  };
}

// Example usage
function demonstratePaymentProcessing() {
  // Scenario 1: Successful payment
  const verifiedUser = {
    name: "John Doe",
    isVerified: true,
  };
  const transaction1 = processPayment(verifiedUser, 100);
  console.log("Successful Transaction:", transaction1);

  // Scenario 2: Unverified user
  const unverifiedUser = {
    name: "Jane Smith",
    isVerified: false,
  };
  const transaction2 = processPayment(unverifiedUser, 50);
  console.log("Unverified User Transaction:", transaction2);

  // Scenario 3: Invalid amount
  const transaction3 = processPayment(verifiedUser, -50);
  console.log("Invalid Amount Transaction:", transaction3);
}

// Run the demonstration
demonstratePaymentProcessing();

How detailed explanations should be - your choice, and it is likely that you may get away with being less detailed. And it depends on how well you know the code. And if you know it really well, you likely do not need to be so detailed, as it is not necessary in this case. But if you are debugging your code, or just getting familiar with it, I think it will be beneficial to be more detailed.

Conclusion

That's it! This is how you can drastically improve your code reading awareness by vocalizing explanations of your code, which results in fewer bugs, quicker features, and overall better developer experience. If you like this article, please share it with someone who might find it interesting too. Like my blog? Subscribe to the newsletter.

Got questions? Send an email to commitnobug@outlook.com.