The world is a beautiful place if you can see things simply. But once you are in the software it becomes ugly and you start seeing things in a completely different way. I have seen thing happening so may times – that I felt like writing this one out.
Its story time here – so enjoy!
The “Hello! World”
You must have written a “hello world” program in your life. It’s the simplest program that you can write in a programming language . So I will tell you a story with “Hello! World”.
In a software company, “ComplicateSoft” (henceforth called as “CS” – for simplification!), there was a requirement from a customer to write a program which will print “Hello! World”. But as with any customer, there is a catch – they did not know where will it be getting printed or how many times will it be getting printed. So they said the “Archie” of “CS” make something generic. Actually the customer said “make something which will do the job in most cases”, the “Archie” documented it as “generic”.
The Dev-Archie meet
“We will do it the proper way”, said Archie.
Dev guy, “Yeah, makes sense – cool.”
So the dev guy wrote a good old Java class, which has a simple method which prints “Hello! World”.
Dev was happy as he never got a easier project than this. So he even wrote it in TDD.
Archie came along and saw that piece of code and said, “Okay, but that’s not generic enough. Dude, make the string “Hello! World” externalized”.
So the dev guy, did.
Next, Archie said, “Dude we do not know where this will get printed no sys-out. Take a output stream instead!”
Well this should be all. The dev guy did that.
Next, Archie said, “This class is doesn’t have any state so lets make it a Singleton.”
The dev guy thought wow! I will implement a design pattern now on this – cool.
The Archie said, “Now we have to make sure that if someone request this as service over the web, do a WSDL for it and test it with a client.”
Dev guy did that!!!
Now Archie thought about the requirement once more and remembered the phrase, “don’t know how many times will it get printed.”
If it needs to printed multiple times with a distributed file system?
He asked his dev guy a final thing – “Can you make this class support Hadoop map-reduce”
The dev guy ….
The end.
Hope you enjoyed.
Tuesday, May 17, 2011
Monday, February 28, 2011
Why is it harder to read the code than writing it?
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.
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.
Thursday, February 17, 2011
10 Things to Keep in Mind while depeloping a Web App
What should I ensure before I start developing a web application? So here is my humble list of things that I must do (don’t) in the future:
1. There is a need for authentication so figure that out first. Use a well know library for it – like if you are using Java use Spring Security.
2. Do not write your backend first. Especially for Ajax based web apps. You will need to add or change the API with the page design changes.
3. Do not return HTML from any Ajax API ever. Use JSON. [If you do this with # 2 you are doomed]
4. In your HTML, JSP (or ASP) or XSLT - do not write the style attribute (in HTML tags) to save time today. Instead add a class in your style.css file. It will save a lot of time in the future. Like if you want to change the color of the whole page you can work with one css file instead of all your ASPs and JSPs.
5. Have one entry point for all services – use a dispatcher. What I mean by this is make your web app configuration lean (for Java world it is web.xml).
6. Keep the logged in user in a secured URL like HTTPS. Never transport password over HTTP.
7. Try to standardize the JSON response. If you need to render something from JSON data this will help you a lot. You can write one helper JS function which will take care of it.
8. Follow css box model always. No excuse.
9. Divide the web page into multiple parts. Each part should be working fine. I mean as much as possible.
10. Build a feature a close it for today’s requirement. Do not jump to a feature without finishing the one in hand – it will bite your ass later.
10 + 1. Test in a lot of browsers (IE7+, FF, Opera, Chrome)
1. There is a need for authentication so figure that out first. Use a well know library for it – like if you are using Java use Spring Security.
2. Do not write your backend first. Especially for Ajax based web apps. You will need to add or change the API with the page design changes.
3. Do not return HTML from any Ajax API ever. Use JSON. [If you do this with # 2 you are doomed]
4. In your HTML, JSP (or ASP) or XSLT - do not write the style attribute (in HTML tags) to save time today. Instead add a class in your style.css file. It will save a lot of time in the future. Like if you want to change the color of the whole page you can work with one css file instead of all your ASPs and JSPs.
5. Have one entry point for all services – use a dispatcher. What I mean by this is make your web app configuration lean (for Java world it is web.xml).
6. Keep the logged in user in a secured URL like HTTPS. Never transport password over HTTP.
7. Try to standardize the JSON response. If you need to render something from JSON data this will help you a lot. You can write one helper JS function which will take care of it.
8. Follow css box model always. No excuse.
9. Divide the web page into multiple parts. Each part should be working fine. I mean as much as possible.
10. Build a feature a close it for today’s requirement. Do not jump to a feature without finishing the one in hand – it will bite your ass later.
10 + 1. Test in a lot of browsers (IE7+, FF, Opera, Chrome)
Subscribe to:
Posts (Atom)