The Most Important Coding Guidelines

C’mon, it’s not that hard. When you start a new job or project, when you enter a new team, it is really helpful to agree on some coding guidelines. You don’t need a whole book. One page is actually enough. But there are things, that you definitely should mention on this single page.

Let me give you just a few of them. Actually, there are only three which I think are must-haves. I don’t care about the rest. Forget prefixes for example. If you feel the need to add the “str or “f or “m_ in front of your variable, well, then do it. If you’re coming from the C++ world and just can’t forget these certain styles, I’m okay with it. But please, don’t miss the following guidelines.

KISS or in another word: Simplicity

Yes, I know you heard it a thousand times and here is the next guy praising this rule. “Keep it short & simple or “keep it simple, stupid”. It is definitely one of the top three guidelines.

I know, regular expressions are so cool and, oh, you’re using binary flags instead of simple booleans, you’re such a great programmer! What’s that? You cut this 30 line method down into 5, but added 10 lines of comment, because nobody understands this algorithm including you next week? Don’t do this.

You know what great code is? Code that everybody understands. It is really that simple. There are exceptions, of course. Use this standard regex snippet if you want to validate the entered e-mail address and maybe use binary for your rights management system. But please let these things be exceptions.

And it’s not only about these techniques. When you think about an algorithm and you might think it’s too easy, maybe not brilliant enough, stop right there and use exactly this algorithm you have in your head right now! If it can be improved, maybe do it while refactoring your code anyways. But keep in mind that other people – even your future self – will read your code eventually and don’t want to have a hard time again to get through your ingenious lines.

Keep it simple. Really. Use your if-statements, do it with a foreach if you think that’s easier to read. But never ever get to the point where you want to be a code magician that doesn’t want to reveal his tricks and nobody knows how she did it anyway.

Show consideration for your co-workers. Thank you.

Naming

Robert C. Martin said it quite early in his book “Agile Principles, Patterns, and Practices in C# and I also think it’s very important: Give your variables, members, methods, and classes names, that do not need any further comments or documentation.

Again, there are valid exceptions. An “int i in your for-loop is okay. But if you’re iterating through a user list with foreach, don’t just use “u”. Call the current value “user”. Or even better: currentUser. I mean, why not? Is it really that hard? Do you lose so much time writing a name that is a little bit longer? By now I really can’t stand all these single character variable names. What’s object “o”? Or string “str”?

The same goes for method names that give me the right idea of the method’s purpose. GetUserName() should give me the user’s name and return it. PutUserProfile() should make a call to a web service and change the user’s profile information. And it should not do more.

If you find yourself thinking of a method that could be given a name like RegisterNewUserAndSendConfirmationMail() you may think about refactoring your code, which leads us to the last important guideline.

Lines of code

Don’t get me wrong. Lines of code is never ever a valid benchmark for quality code. That’s not what I’m talking about in this section. It’s not about how little code you write, it’s about how big your methods and classes are.

They say make methods not larger than your screen size. Well, that’s not very precise. Let’s say, your methods should have no more than 30 lines, your classes 500 to 1000 lines max. Now, this doesn’t mean that you take your 300 line method and simply split it into ten consecutively numbered methods. No!

This rule should make you think. It’s more of a design rule. Nobody will fire you when you have a 31 line method. But you should always ask yourself if you can design your classes or methods in a way that would suit into this guideline.

Consider the method mentioned above, which registers a new user and sends a confirmation email to the user. You might have already guessed it, you can make two methods out of this. Even better, you can implement the SendEmailConfirmation() method in a way, so that other methods or even your co-workers are able to use it.

As I said, that’s more a guideline concerning design rules or patterns. And that’s enough content for another blog post. But for now, just remember these three simple ways to code:

• Keep it simple stupid (KISS)
• Reasonable naming
• Short methods and classes

If you still don’t believe me, wait until you have to make changes to a class that has 60.000 lines of code. Sixty thousand. I’m serious. Don’t be that programmer. Thanks.

This post was originally published on programmergoals.com

But wait, there’s more!

• Let’s connect on Twitter, Facebook, YouTube, LinkedIn or here on dev.to.
• Get the 5 Software Developer’s Career Hacks for free.
• Enjoy more valuable articles for your developer life and career on programmergoals.com.