I am not sure if the 'spam' was intentional, but since the site is not back up, and since I do care about this topic, I pulled the content from Google Cache. I have included it below, just in case Google flushes its cache. -- Founder, Architexa [email protected] :: 617.818.0548 www.architexa.com - Know Your Code
=========================== "How To Make Your Java Code Understandable" - http://www.agilejavaoop.com/java/how-to-make-your-java-code-understandable/ You may be working on the develop ment of a sys tem at your company. You have been working in coding some module. And, it has been around 6- months since you last worked on that module. Today, your manager has asked you to make some modifications to that module. You said to your self: “Well, that is no problem at all, I have coded most of that module, and really very aware of how it oper ates”. You fired up your favorite editor. Your fingers began tingling. And, you are ready to the coding. You headed directly to the required class to start your oper a tion. “Yes, this is my code. Look who’s the author (@author)”, you said confidently. So, let the oper a tion begin. What is the problem?! Why are you staring like that?! And it stopped there. Have you ever gone through such scenario? So, as you can see, this may hap pen to us with our own code. But, why is that? Yes, you may be documenting the code, or having comments for specific parts of the code, but, at the end of the day, you may be wondering why you even did that, what was the reason, and many many other questions that may come to your mind. If you fall in such cir cum stance, we can say in brief that the code is NOT under stand able. What good in a code if you or others can not under stand how it works and what it is about. The case is really sensitive here. Yes, we have to make our code understand able even with out commenting. One way to do that is to make the code clear and obvious to see what is happening. I think it is now time for an exam ple to make what we talked about so far more clear. Assume that you have the fol low ing line of code: coffeeShop.placeOrder(1); Is this code understandable? Well, we can understand that we are placing an order in a coffee shop. But, the question here is: What are we actually ordering? 1?! What good in a code if you or oth ers can not under stand how it works and what it is about. So, it is not clear from the code what we are trying to place. A way to solve this issue is by adding a comment as follows: coffeeShop.placeOrder(1); // 1 is small cup size But, we don’t want comments to com pen sate for this poor code. We want the code to be understand able in its own. A workaround for this would be in defin ing an enum as follows: enum CoffeeSize {SMALL, MEDIUM, LARGE } In this case, the placing order code could look as follows: coffeeShop.placeOrder(CoffeeSize.SMALL); Look at the code once again. Isn’t it more descriptive? And, thus, understandable? So, what we learned here is what’s so called the PIE (Program Intently and Expressively) principle, and it states the following: Code you write must clearly communicate your intent and must be expressive. By doing so, your code will be readable and understandable. Since your code is not confusing, you will also avoid some potential errors. Program Intently and Expressively. Abder-Rahman Ali -- You received this message because you are subscribed to the Google Groups "The Java Posse" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/javaposse?hl=en.
