The Principle of Least Surprise

©️ Be consistent. If you do something a certain way, do all similar things in the same way.

The less surprise, the better

☝️ Software engineering is a lot easier in consistent systems.

Consistency inside a system allows you to make more accurate assumptions and predictions about code behavior and implementation. These assumptions are crucial tools developers use to feel their way around larger, older systems when they can't fit the codes in their heads.

Making your code consistent increases the quantity and frequency of accurate assumptions, and these correct assumptions (and verifications) lead to the many steps you take during development.

✌️ As the code becomes consistent and predictable, it ends up becoming reliable, avoiding surprises.

Whether you are working independently or collaborating in teams, you would always want as many people as possible to quickly understand your code to be able to expand it and help your project grow. If your code remains the same throughout the whole project, it is much less painful for others to understand and extend it.

The three levels of Code Consistency

Level 1: Individual Consistency

At its most fundamental, consistency simply means being consistent with yourself when there is little standardization in our company, or when we work alone. Here are some key tips so you can start working on your code consistency:

• Name things consistently: things should have one, and only one, name throughout the whole project, be it actual code, variable names, or even comments.
• Pick one code style and stick to it: no matter how many people are there in the team, the code should always look like it was written by a single individual.
• Have one way of doing something: try to establish The One True Way for each process of your project, whether it is uploading images, setting up routes, or iterating over a collection.
• Make things match: one single change may seem small and insignificant, but many small changes together may snowball into one painful root cause over time, so make sure you get every small stuff right

Level 2: Collective Consistency

At the next level, and here we assume there to be code from other developers or third parties, consistency means following the code style used wherever we touch code. We should respect and stay consistent with the code style prevalent in the files we touch.

Level 3: Institutional Consistency

At this final level, consistency means sticking to the company’s coding guidelines and style guides. If the standards are well-established and enforced, this level of consistency has the most power to even influence behavior changes in coding behaviors, those that individual consistency has absolutely no reason to do so, and collective consistency only briefly.

Code Consistency in Practice

When coding on our own, we should at least strive for level 1. When working with others, we should at least aim for level 2 - respect their code, but only if there is a lack of a wider standard. When in Rome, do as the Romans do, so if you touch something in their domain, write codes as they would.

When we are in a bigger organization, the idea of level 2 prevails, but we can now think of setting up standards to operate at level 3. From there, we can marry the two levels - follow the guidelines, but when there is something that violates the guidelines and not enough time to reformat, stick to the prevalent style.

To change or not to change

One big question you may face when coming across codes that need to be improved is whether you should change them or not? Based on the code consistency, isn’t it better to leave it consistent rather than making a change that may lead to a bigger problem?

Improvement is not always a bad thing, only if you improve smartly. Now here are a few tips:

• Weight the tradeoffs: suppose your new approach is better, you still, however, need to analyze all the scenarios that would follow this lack of consistency
• Ensure complete adoption: now that you have decided to go with this new approach, better make sure that the old one is wiped clean off your codes to avoid problems piling up in the future
• Fake it till you complete it: it is not always possible to swap out the old method completely, that’s why you can utilize design patterns to keep the old stuff under the rug with your new approach
• Ensure clear lines of adoption: now that you have installed the new approach and kept the old one under the hood, the separation line between them must be distinct, if you can’t maintain consistency across the entire system, keep it within software verticals or modules

Closing

Speaking from experience, being aware of these levels alone helps a great deal in writing more consistent, and with that, quite better code. Happy coding, folks, and remember to stay consistent! Stay tuned for more coding principles from our tech team!