Legible Coding
18 Sep 2022Why it matters if others can understand your code
Who Cares if others can’t read your code?
It has been a little over two years since writing my first line of code. That accelerated summer course in C programming was both enlightening and frustrating. At the time, I didn't think about how my code was written or how legible it was; my only priority was to get the bloody program to work. It was only when a teachers assistant brought it to my attention that she couldn't give me partial points for my work due to its illegibility that knew I needed to change something. From then on I tried replicating professor and TAs style of writing. I made indents within a coding block, gave my brackets their own spaces, and wrote comments after a statement just to name a few changes. Most importantly, I gave my programs structure which enabled those who were grading my work the ability to see my methods and thought process for my approach in solving problems. Once that class was over, I kept the same format for all programming related work. I didn't think there was an actual way of writing code that is widely recognized by many; a sort of "coding standard". That was until now.
Why is this important to me and why should I care?
- A coding standard gives a uniform appearance to the codes written by different engineers.
- It improves readability, and maintainability of the code and it reduces complexity also.
- It helps in code reuse and helps to detect error easily.
- It promotes sound programming practices and increases efficiency of the programmers.
- Limited use of globals
- Standard headers for different modules
- Naming conventions for local variables, global variables, constants and functions
- Indentation
- Error return values and exception handling conventions
- Avoid using a coding style that is too difficult to understand
- Avoid using an identifier for multiple purposes
- Code should be well documented
- Length of functions should not be very large
- Try not to use GOTO statement
Personal Experience With Standards
Out of that long list of common practices, it appears I have surprisingly been practicing a small fraction of them all along, yet I have barely scratched the surface when it comes to implementing coding standards in my own work. Understanding this earlier in my coding career would have been of great help when it came to working on group programming projects. Not only did it make it slightly more challenging trying to decipher my group mates work, with all of our different personal standards, but our work always seemed to be missing a sense of uniformity and professionalism that I would see in popular and well managed repositories. While it did seem like extra work before, being introduced to Integrated Development Environments (IDEs) such as IntelliJ IDEA and plugin code editors like ESLint has left me with feeling like most the the work is done for me. Now, I can focus on solving problems and rely on those tools to keep my code neat and uniform within a set of standards.
Now what?
Although coding standards change based on the people, companies, or projects you work on, it is best to get used to them. At the very least, being able to understand them and to apply them into your code at any given moment. Like moving to a different country, it would behoove you to adopt their customs, courtesies, and language. To be able to communicate effectively, to understand others and to be understood is the most important factor when it comes to your success a programming environment.
For me, I will continue to do my best to add some of those standards in my everyday coding and stay open and flexible to applying new ones to assimilate to my current coding environment. With the plethora of tools available to us, what do we have to lose?