jay's old blog

this blog will be deleted soon - please visit my new blog - https://thesanguinetechtrainer.com

Making your code readable

There are several things that are frustrating and comes with the territory of being a developer. Updates that break your IDE, system updates that suddenly outdate an DLL and slow internet access. Some of these are outside our control and others are manageable. However, one thing that should be avoidable but almost seems to be ignored is making the code readable. 


Code readability is not just one thing. It’s a combination for several things. For instance, a lot of times, there are literally zero comments written by the original developer of the software project. When that developer leaves (to another project or to another opportunity at another company) the ones that are now tasked with maintaining that code are stuck in an endless loop where fixing even trivial bugs takes ages because we are left searching for a needle in a haystack because the developer took his magnet with him. 


That is why, making code readable is important. I have seen a lot of developers (in fact, I am yet to meet anyone in person who documents anything which makes it all the more depressing) who simply go by 'memory'. Or perhaps, they like it that whenever there is even a simple issue, everybody calls them and asks them for help. Maybe it makes them feel needed, which is frankly a waste of time. 


Nevertheless, personal feelings and ego aside, not documenting is a dangerous and a sign of coding immaturity.  


meaningful names 


Meaningful names are the crux of readability. Personally, I give meaningful names to everything. When a new create a new project, I give it something like 'demo_calculator_students' instead of 'ConsoleApplication26'. The letter indicates that it is a console application and not much else. The former, informs me (and other developers) what the project is about.  

I also give meaningful names to classes, methods, variables, method parameters and anything else that needs to communicated via a name. This extends to temporary (variables that have as well as permanent variables, enums and constants.  


Notes 


Every time I create a new project, I always include a simple file called 'notes.txt'. This will play no role in the actual app itself. However, in this notes, I put everything that I did when building the project. It's almost like a diary.  


I will try and make notes with dates. As in which classes were created when. What bugs were discovered and what online resources (MSDN, stack overflow) I used to fix them. I will also include notes about how I solved a particular challenge which includes algorithms used and new logics that were created.  


The idea is to make sure that when another person opens the project, he can use this notes document to find out what was being done while this project was being built.  


Comments 


Why don’t people write comments? I am convinced that at least some percentage of my hair loss is having to do with debugging code written by others without as much as a single line of comment as to what a code block does or does not do.  


Comments work hand in hand with the notes document I mentioned earlier. The difference is that, notes document is like a comment file for the entire project while also acting like a diary with daily work entries. Comments related to a specific method, comments related to a specific condition statement. The beauty of comments is that, it tells the developer exactly why a particularly comparison was done, why a method has two parameters, why a object was made null and so on.  


Without comments, even the most brilliant developer will take a while to realize why a particular statement or method call or object was written the way it has been written. 


Regions 


In Visual Studio, there is this thing called regions. Regions is how you divide your code into 'zones' with each zone serving a different purpose. For instance, at the beginning of your code file, there will always be a list of using statements. Sometimes, these using statements can run two pages, and if you are working on incredibly expansive project, perhaps even more.  


Everytime you open the page contain so many usings, you will be scorlling, paging up and paging down so much, it consumes a lot of time. You can put the entire thing in a 'region' and then this two page thing gets folded (which can be later unfolded) into a single line. Thus, making your code look slim.  


It's a good idea to 'regionize' related items like related methods, related function calls, variable declarations and so on. Proper usage of region can turn a 100 page code file into a two page file, which makes code traversal that much easier. 


Flowcharts 


This may be a little excessive but I prefer to write a lot of flowcharts. When you are designing something new, you should consider writing flowcharts. Then, once the flowcharts are done, take a photo of it, upload them to your cloud drive and include a link to it in the notes. 


Follow me on twitter, facebook and instagram for more updates. Thanks!

Comments are closed