What I learned after coding for a year
By: Ajith K
Tags: Coding, Java, Best Practices, Programming, Software Development

Writing a program is hard. And writing a maintainable program that everyone can understand is really harder. It takes a lot of time, practice and dedication.

Today, I am going to share what I learned through my one year journey as a software developer. This helps you to avoid these mistakes as early as possible. We start with a sample program given below. And we try to improve the program while looking at each section.

Note: It’s an illustration, not a complete working application.

If this program looks familiar, then you must continue reading further. As the program tries its best to describe as a note-taking app, it hardly conveys its intended purpose. After looking carefully for a few times you may start to realize the purpose of this program. Why its hard to read? Because it’s poorly written. Although the program works properly its hard to understand and maintain.

So let me share some of the basic principles and guidelines that you can follow to write a better program.

Formatting and Code style:

Formatting allows us to comprehend the code without any efforts. Without proper formatting, the code becomes hard to read and maintain.

Look at the above program. The braces are not indented properly. Either place opening braces at the new line or at the end of the same line. Follow any standard code style guidelines and stick to it.

Comments:

Comments are the easiest and, at the same time, the hardest part of coding. Because comments are hard to maintain than the code itself. Avoid comments as much as possible. Add comment only when required.

In the above example, the comments are not self-describing. And it also has useless comments. See line number 3 and 6.

Naming Convention:

Naming a variable, class, methods, or anything must tell the purpose to the readers explicitly. Do not name anything that doesn’t convey the purpose.

For example, in Java we follow conventions like the class names should start with a capital letter, method names should follow camelCase, and constants should be all capital letters, etc.

After applying all the above guidelines and principles, now the program looks like this:

Isn’t it looks better? But still, there is room for improvements. Let’s see them.

NULL and Magic Numbers:

null is the most mysterious keyword in any language. So, avoid passing and returning null values. Because it does not convey whether the object has no data, or its empty, or something is broken, or whatever.

Use exceptions whenever you want to notify that something went wrong. Use empty objects to denote emptiness.

And don’t use any numbers without making it a constant. Later you find yourself digging what this number supposed to mean? Make magic numbers as a constant so that others can understand its purpose.

Datatypes:

Always store data in datatypes that are meaningful. Because sometimes you may get confused, say, whether should I parse this as a Boolean or String.

return "true"; //bad. return true; //good.

Function Length:

Never allow any methods (functions) to exceed more than 10 or 15 lines of code. Even though you may not call that method more than once, split them into one or more methods so that each does a specific task. This allows you to easily test and maintain the code.

Don’t Reinvent the Wheel:

For almost any task, there are many APIs available already. Try to use those APIs other than for learning purpose. And create only when it does not support your need efficiently or when it’s not customizable.

Refactor:

Software builds with changing requirements. Which means you have to change the code now and then. So whenever you modify something refactor the existing code. Because you are making a mess by modification, and you should clean it up. Otherwise, it becomes a maintenance headache as the system grows.

Now take a look at the below program that followed everything I just described. Its cleaner and easier to read. Compare it with the first program and see the difference.

Always TEST the code:

This is the most important part of software development. Yet easily overlooked by all of us. Even if you change a single letter in code, test the entire module at least, if not the whole system. Because software easily break. Try to automate the testing process wherever possible.

Happy Coding! Happy Learning!!!