1

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?

  • 2
    Programmers have a tendency to fight over effectively nothing. It's nice to keep a relatively consistent style in the same given file of code, but if it can be fixed with a few simple regex, or a decent IDE, it's not worth arguing over. (Comment because I felt this isn't deserving of an answer) – Assimilater Sep 30 '16 at 4:14
  • The point of a style guide is to clearly lay out the style guidelines without guessing about things. Don't assume anything about the "language's normal style". What exactly is that anyway? – Brandin Sep 30 '16 at 6:46
  • Dont waste your time writing documents – Ewan Sep 30 '16 at 7:34
  • Sigh, no. It's good to write documents. We face an arbitrary style decision. We flip a coin. New guy comes on it's nice to tell him what the coin said. Just keep in mind that code is the ultimate source of truth. A style guide is only a report of what the last dive into the code, and coin flips, told us to do. Reports need updating. New guys need a reason to sit and study the code. Hmm... – candied_orange Sep 30 '16 at 13:04
2

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.

0

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.

0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.