Best Practices For Coding (Readability)

Good morning everyone! Hope you all had a great weekend!

Today marks the start of my mini series of blog posts on the best practices for coding. If you haven't done so already, I strongly recommend that you read my blog post on Friday, which can be found here:

Best Practices For Coding (Intro)

What is meant by "Code Readability"?

Code readability basically means how easy it is to read the code that's in front of you and understand what it is supposed to be doing at a glance without having to do too much digging around and investigating. Code readability is good for multiple reasons:

1. It proves that you, as the developer who wrote the code, understand what has been written and why it accomplishes the job that it does.
2. It helps other developers who may need to view or expand on your code in the future.
3. It helps you determine whether you have used the best programming practices to ensure you have found the best solution for the job. 

During my time in the work place, I have seen just how easy it is to slip into bad habits, which get picked up at the peer review stage and have to be rectified before a second round of peer review is conducted, which can waste time as the initial developer should be thinking of readability in the offset! The purpose of this blog post is to highlight how to make your code more "beautiful" so it is easier to be read and reused by other developers.

Examples of Bad Code Readability

Below is an example of code that has poor readability:

Examples of Good Code Readability

Below is an example of code that has good readability:

See the difference?  The top example has no comments, no indentation, a variable name called "a" with no explanation via comment what "a" actually is and variable declarations are sometimes in capitals and sometimes in lower case. Personally, I find that quite difficult to follow. The second example however is much better as it has been indented and commented properly, plus a consistent naming theme has been put into use. And these are both the same function that perform exactly the same functionality, just laid out differently. Isn't it interesting how different they look from each other?

Tips On How To Make Your Code "Beautiful"

Personally, I prefer looking at code that's "beautiful" as it's easier to read, digest and learn from. I use the following guidelines to help me make my code more readable:

Sensible Commenting

Commenting code really helps others understand your program. Not only that but what if you take a break from a project and come back to it at a later date? What you may have understood at the time may be confusing to you now as you cannot remember what certain functions may do, and it may not look obvious by looking at the code alone.  Ensure that you do make comments to your code to make it easier to understand.

However, some developers take this very “literally” and comment every single line of code, even if it is pointless and it is very obvious what the line of code does. This is not necessary and can actually cause more hindrance. There is really no need to go overkill, it will just mean you will have to trail through lots of comments in order to find the what you are looking for, which is time consuming and very avoidable.

Consistent Indentation

Code naturally forms an indenting structure. The purpose of this is to make it easier to see where functions, loops, if statements etc. begin and end. Most IDEs (Integrated Development Environments) have their own way of correcting indenting format so that it is consistent throughout the source file, making the life of the developer much easier. However in SQL, this isn't the case and there is no control. As a rule of thumb, I always tab in code if it is:

• Between a BEGIN...END statement.
• Within an IF statement.
• Nested. 

It really doesn't matter too much with SQL code, providing you use a consistent indentation theme, then you'll be fine. 

Consistent Variable Names

So you've named your tables, views and columns using camelCaps. Really, you should be using the same practice in your T-SQL code variables as well as this improves your consistency. Again, ensure that you stick to just one (sensible) naming convention and preferably use the convention you have used to name your tables. As a reminder, the 2 common practices are:

• camelCaps (or camelCase): The first letter of each word is capitalised, except the first word.
• under_scores: Words are separated by underscores.

Use The Right Control Flow Statements

As mentioned in my previous blog post series about transactional flow, certain control flow statements such as BEGIN...END and IF...ELSE actually aid code readability as it is easy to follow the flow of the code. However, using statements such as GOTO can cause problems and make it harder for you to read, particularly if you use a lot of them. Always keep code readability in mind when selecting the right statements to use!

Code line lengths and wrapping

Not only is it difficult to read when the line of code scrolls off the page, but if a developer is viewing the code on a relatively small screen/small screen resolution, they will have a nightmare attempting to follow the code through. Also, if you wish to print your code it will become more difficult if it overlaps horizontally on A4.

Although this is a matter of preference dependant on the developer, 80 characters is the traditional length and most programmers adhere to this standard. Consistency is key! Make sure that all of your source files and query files have the same code line length.

Capitalisation of keywords

It may also be a good idea to capitalise any SQL keywords as it will make it easier to distinguish them from a block of code, particularly if it forms part of a long source file or query.

Conclusion

As a conclusion, I hope you have seen the importance of code readability and the impact it can have on your code. Obviously, it will still work without it but why not go that extra mile and show that you not only can make code that works, you can make elegant code that works!

What's Next...

Stay tuned for tomorrow as I will be discussing code accessibility, something which should always be at the back of a developers mind when they are programming anything as you don't want to waste time and effort on an overcomplicated solution!

Thank you for reading today's blog post! If you have any questions/comments/feedback, please leave them in the comments section below and I will get back to you as soon as I can. Alternatively, please like my SQL Genius Facebook Page and leave a message on there. Thanks! :)