Code Quality & Code Requirements

Tired of the privacy invasion of browsers? Worried about the risk of seeing ads everywhere? Give the Brave Browser a try. All Chrome extensions are compatible. None of the telemetry. Auto-blocks ads and still support content creators like me.

Download the Brave browser now »

Profile image of Mattias Geniar

Mattias Geniar, November 13, 2008

Follow me on Twitter as @mattiasgeniar

I’m a programmer by heart. If I don’t do it by day, I’ll do it by night.

This is what I do, and it’s probably what I do best too. I write code. I scribble down thousands of lines, to overcome a certain problem situation. Hardly anyone knows what it means to do so, unless they are fellow programmers. To everyone that doesn’t understand what it means to program, a “good application” will be one that does the job. Simple as that.

To those that understand the mechanics, and the reasoning behind programming, that is entirely different. For them, it’s not just the matter of an application doing what it’s supposed to be doing, but also a matter of “how” it’s done. How “effective” is it? Is it fast? Will it work cross-system? Will it keep working in five years? Was it written with maintainability in mind? Was it written in a  clean manner, or with sloppy code?

For a typical end-user, “code quality” doesn’t mean anything. But it has a variety of meanings for those others that play the game. And for those, “the code” has certain requirements (or at least, it should have).

Code should be documented – not for what it does (after all, the code is right there in front of you – to *see* what it does), but why. Why is this piece of code needed? Why did you do it this way? Why not via another path?

You should feel obliged to explain yourself, to stand by your decision for the question “why I did it this way”.

Code should be public – for learning purposes, both yours and others. While it’s not possible in every project, others should be able to see your source code, to learn from it, and to point out possible (security) mistakes.

You only have the knowledge of one person, those who read or evaluate your code have the combined knowledge of possibly millions. By definition, that’s better – right?

Code should be structured, to follow the general guidelines. Think of variable/method naming, good practice solutions, patterns, … Keep both your syntax and your logistics in place. It’ll help yourself, as well as others reading/expanding your code.

Code should be discussed, before you begin writing it. Talk about your problem, the solution you have in mind, and your method of implementing it. Again, two people know more than one, so talk about your solution. Listen to other solutions, and draw your conclusion.

It’s possible you had a more complicated solution. That’s good – it means you learned something. A simpler and more effectiv method of dealing with a situation.

Code should be correct, in every possible way. It should solve your problem, but it should solve it correctly. Not by “trial and error”, but by means of understanding the problem, and by supplying the proper fix – knowing the solution is 100% fail-proof.

The idea of “guessing” for a correct answer is both wrong for yourself (you don’t know how to do it, so you’re just typing away hoping to find the answer some day …), and your target audience, who might one day run in to bugs.

Code should be corrected, as an expansion to the previous topic. While code should be perfect, it hardly is – despite your amount of testing. It should then be corrected, to fix the issue. It should be corrected by means of understanding. Know what went wrong, learn from that mistake.

Code should evolve with time. What might prove to be the solution now, could very well be outdated in a couple of years. Techniques evolve, and your code should adopt it. More effective and secure methods are built, it would be foolish not to take advantage of it.

Code should be evaluated, by yourself and others. Set up test cases, possible scenarios and possible user interactions. Get help testing, because you can’t do everything yourself. Evaluate the code in different situations, on different settings, and at different times by different people.

Get reactions. And react yourself.

Want to subscribe to the cron.weekly newsletter?

I write a weekly-ish newsletter on Linux, open source & webdevelopment called cron.weekly.

It features the latest news, guides & tutorials and new open source projects. You can sign up via email below.

No spam. Just some good, practical Linux & open source content.