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.
Oldest comments (5)
Great article! My programming "childhood" was during the first dotcom boom, and I was raised on mantras of "Thou shall not violate the standards". Of course that led me to desire enforcing standards. Thank goodness I saw the light!
These days, I lead a team where we are mostly not picky about coding style. If one of us reviews code and we can't get a good sense of it's purpose within a moment or two, we call it out to each other (nicely of course). The result? A much happier, trusting and performant team...something that I didn't expect.
Thanks, Chris. And thank you for sharing your experience. Sounds great! :)
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Martin Fowler dixit.
Nice list, Patrick.
If there was room for one more thing on your list I would vote for automating your rules with some kind of static analysis tool.
Have you tried that? If so, do you have any tips?
Thank you, Blaine!
There are several tools that can help you writing readable code. ReSharper and the integrated StyleCop are tools we use in our team. For instance, it reminds you of proper naming or even using simpler code sometimes.
But the KISS thing is something you learn with experience I think. You can even do it completely by yourself. Look at code you wrote weeks ago. If you still understand it in a minute, it might be good code. Too often we write complicated algorithms that seem pretty clever but are so hard to understand that you don't know what your past self actually did there.
However, regarding KISS you have to be careful with ReSharper. Sometimes it wants to replace your for-loop with a "clever" LINQ statement, but as mentioned above, this replacement can lead to unreadable code.
Hope this helps! :)