Writing good code is almost like an artform and takes a lot of time to master. It takes even longer if you don’t know what the core guidelines are. In this article we’ll cover things from proper commenting etiquette to the benefits of writing clean code.

How to write coding comments properly

Commenting is the thing you are used to do every day ( or almost ) in Facebook, youtube and reddit but still for some reason struggling to do that in your code!

The things you should tell the world, or at least your team, about your code are as follows:

• Author
• Name of the module
• Description of the Module
• Modifications
• Authors who modified code with a description on why it was modified
• Add @see referencing the class which will help to easily navigate to that class by using IDE like PHPStorm, with only one click
• Add @todo on the things which are left to be implemented

Another thing to keep in mind is always adding description where complicated logic is involved this will simply let things sort out faster. For the self explanatory and short functions you should not do this.

Here’s example:

Naming conventions for coding

Of course, naming conventions depends on a language you are using ( examples: Zend, Google style guides ( CSS, Javascript, Java, etc )). But the main idea is to use descriptive and meaningful words. So, you should avoid calling your variables: xx, yy2, test1, test2 and so on.

Is your code portable?

These are basically a hard-coded values which are tied to the current environment you are working on i.e. absolute file paths, host names, URLs and stuff. Also avoid magic numbers and keep this in mind!

Keep your code simple

Yes, all geneal things are simple in their nature and same should happen with your code. There is no need to complicate simple things, so stop doing that right now! Also avoid long functions and deep nesting!

A real example of writing good code

Here I just want you to tell where you can find these examples. These examples can be simply found in the CMS or frameworks you are using at the moment, such as Magento. Just open up any php class, html, css or xml file from the core modules — there are plenty of examples! You simply need to follow them and remember.

Ok ok, let me show you some!

Here’s classic example for CSS property “color” that you all know:

Now what you should know here is that you can write it like this:

And this is what makes your code shorter! Not only the fact that it is shorter matters but that less data will be sent over the internet — which is good!

So what are the benefits of writing good code?

Good coding standards can offer many interrelated advantages, such as:

• Improved code quality
• Improved development speed
• Better teamwork
• Uniformity in the right direction — which frees developers to be creative in directions that matter!

Motivation to write good code

Sloppy programmers who in normal times don’t know good practices of software development will write sloppier and buggier code when pressure is on! Because under pressure we do what we are trained and used to do..

So it is in your interest to form good habits! ; )

Advice for good coding habits

When you start to work on the project in progress which has different code style that you used to develop, keep on using that initial coding style ( unless you agree as a team to use your preferred coding style ) — this will make your life easier. And I truly believe that as a good programmer you can adopt to any coding standard which is out there in almost no time! 

Questions to answer

Do we need to standardize everything? Are there a moments where we can use coding style that we like or style which does not have any real impact on the code at all?

Final words

Software development world does not spin only around the coding standards, there are lot more of them! (And not only the standards).

Scandiweb is the most certified Magento agency in the world with more than a hundred experienced coders and more than a decade of experience under its belt. We’re here to help, so if you have any questions – drop us a line at [email protected] or check out our services page.

Related articles:

• How to Code Productively: Best Practices from a Senior Developer
• Developers on their way to Paradise
• Code Optimization: Save Time with Profilers

Share on: