Equivalent to "Principle of Least Astonishment" for code style?

Question

The Principle of Least Astonishment is a design guideline that you should make your behavior match what people would expect. Don't redefine equality, behave consistently, choose sane defaults, etc.

At my company we have several code bases which were written at different times by different people in different styles (although all C#). We're working on a style guide for code, and hope to standardize old code eventually, but in the meantime people need to keep working on these code bases.

Would it be appropriate to say that PoLA requires writing code such that it matches the rest of the surrounding code base, even if it's fundamentally different than the language's normal style? If not, is there another similar idea/phrase that can be used to describe that idea? Or am I way off base, and would it be better to write the new code correctly, even if it stands out from everything else?

Answer 1

Be consistent.

Every day perform some random act of kindness to the code.

Yes, do both.

Code rots if it's never updated. That's a metaphor. Sure untouched source works just as well as it ever did. Look at untouched source from the 60's some time. The whole point of source code rather than machine code is that we can read it and change it. While the code may not change we certainly do.

I've worked in code that reflected the absolute best wisdom at the time it was written, from four different decades in the same codebase. Astonishment doesn't begin to cover it.

There is only so much you can fix. Only so much you can drag with you into the future. You must pick your battles. But as new people come on to a project and you watch them struggle to get their heads into old ways of thinking a few candidates for serious updating should be coming up from time to time.

Aside from that the best thing you can do is make clear where the lines are. If the accounting system is famous for being OOP and the provisioning system is famous for being functional then let them have their quirks. At least when I sit down with one of them I know what to expect.

If the auditing system is famous for having a completely unpredictable style it's time to flip a coin and give it a predictable personality. I like it when my chaos comes clearly labeled.

Answer 2

Start with the coding standards document. Base that on the style used by the language itself. That way incoming new hires should be able to understand the code quickly - that in itself is the PoLA you're looking for. In Delphi (C#'s spiritual predecessor) there was a very definite "Borland style" that the Delphi source code was written in and it was unwise to deviate from (although I have encountered a number of deviants :). You should have less resistance using the Microsoft in-house style than "Fred's funky way with comments and curly brackets" although you will still probably get some resistance.

A second suggestion beyond iteratively fixing the formatting as you make changes to each file is to look into automatic code formatters (you could start here) and use them to reformat the codebase of every application to match the coding standards once they have been finalised. That way, everybody's on the same page and the code is all consistent.

One thing to watch for; I once worked at a place that implemented an automatic code formatter on the check-in of their version control system to enforce consistency, which isn't a bad idea. What was questionable was when a couple of the aforementioned "Freds" wrote custom formatting rulesets for their funky deviant preferences and applied them on their check-out from the version control system so they could carry on coding in the same incompatible style they were comfortable with. You may wish to discourage that.

Answer 3

Yes, you have the right idea.

If you have a subsystem which consistently follows different conventions than you overall coding style, then new code inside the subsystem should preferably follow the conventions established in this subsystem.

If you want to change the subsystem to conform to a new convention, it is preferable to do it in one go, or if this is not possible, do it one whole component at a time. Having different conventions active at the same time in the same code is a mess.

As an example: Say you overall follow the C# naming guidelines, but you have a subsystem which for historical reasons follow the Java naming style (camel case methods and so on). The naming conventions are still useful as long as you know which style is active. But if you start mixing the styles in the same code, suddenly you have something which is much less understandable than either style, an not much better than having no style at all.