The Benefits of Making Your Intent Clear When Programming

October 29, 2017

When people ask what makes someone a senior software engineer, they tend to get the same responses: ability to ask meaningful questions, mentoring others, putting aside one’s ego, technical ability and so on. But, there’s one thing that I believe is just as essential that is rarely mentioned: making the intent of your code clear.

This can be accomplished a few ways:

  • variables and functions have clear names that express their purpose
  • functions are small and have only one responsibility
  • code should be self documenting, but if that’s not possible…
  • … comments should be added that explain why the code is written this way, and how it works
  • functions and classes are organized so that new contributors can quickly find what they’re looking for

It’s easy to neglect some of the above when you’re new to programming, or under tight deadlines. But making the effort is absolutely worth it. Your code will be easier to understand, easier to test, and easier to refactor. New contributers will thank you. Future-you will thank you, too. After all, there’s nothing worse than coming back to a codebase you wrote 6 months ago and wondering what the hell is going on. So take the time now to make your intent clear - even if it only helps future-you, it’ll be worth it.


Hi, I'm Steven Mercatante.
I build awesome things for the web using Python, JavaScript and Elixir.
Contact me if you'd like to work together.