It is harder to read a code than to write it.
In a meeting where a team is deciding whether to write the code a fresh, this is the reason given in favor of writing it all over again. With this reason we sometimes add seasonings like: we will design it better, we will write in TDD, blah, blah and blah.
But if you think very closely you will come to know why you are re-writing the code. If you are re-writing a code from language X to Y. There must be some very good reason behind it. Like if you have a old C code which you want to re-write in Java your list of reason could be: portability, multi threading, OOPs design, security etc.
But if you have decided to re-write the entire code in the same language you are doing so because:
It is harder to read a code than to write it.
Now stop think about the part:
It is harder to read a code
Why is it harder to read the code?
Answer the following questions:
1. Is there a high level documentation to follow the code flow?
2. If I put a break point in main (for C/C++/Java – you can think of the name of the entry point method in your project. In a web development you can think of a Servlet also.) can I follow it?
3. Are all the “if statements” (even assert statements for debug) is well commented?
4. Can I test all the methods for their side effects and returned values?
5. Can I look at the output of the program and get to know which paths are involved to produce any part of the output?
If your answers are mostly “No”. You need re-organization of your code – not a full blown re-write. That re-organization can be: adding comments to full refactoring of the code. But here I will tell you a little bit more about each point that I have mentioned above.
• High level program flow is very crucial for understanding of the software. A full-blown call graph tree is perfect. But at least all programmers in a project should be able to draw the high level program flow easily. Now let me tell you that this high level is not a one block with input to output. It has to be at least describes all the major boxes in the system. It should show the interaction with various modules, including internal and third party modules used.
• One should be able to go though the whole system effortlessly when she has put a break point at the beginning. Now if you have multiple entry point (one for one feature), one should not look out for an entry point for particular feature more than one documentation file. If you do not have it – do it now.
• The branching statements in a code are very important. This is the place where business logic is implemented. So they must be documented – and the documentation is in the code as comments. You do not want your programmer to look for the spec while debugging any feature. Any changes to the business requirement should be tracked in the code comment. If any of the method is going to change the state of some variables or objects which impacts the overall behavior you should document that also, again in the code comment.
• Nothing is like a unit testing but that is less for automation and more for human understanding. Any developer in the team should know where the unit test case resides for the method that he is working on. A new developer should start by doing the unit tests first. Sometimes in old code we do not have unit test cases for historic reasons. If that has state changes going around we should provide the developer a way to understand the state and state changes.
• This one is important! Look at your output and tell me which code or code path is responsible for this output. Like if you are showing a count of students in a class you should be able to trace that front end to the back end code till the DB.
If you do all that you should be in a good position to understand the code and work with it rather than dispose it off. If you anyway decide to follow the re-write make sure the documentation points that I have mentioned here. Do the docs for this re-write else you will drop this code some day with the reason:
It is harder to read a code than to write it.
No comments:
Post a Comment