June 16 came and went last week without me realizing that it would have been my 5th anniversary in my former company had I not departed from it. Not that I had a reason to remember, though.
However, once I had realized it, I couldn’t help but ask myself the question:
If you would go back five years in the past, what advice would you give your past self?
Code Comments: novice programmers either use too much or too little, while so called “experienced programmers” don’t even know where they should be placed.
Actually, the proper use of code comments is one of the issues in software engineering with the least amount of debate. Overall, there are only two rules of thumb to keep in mind when using code comments.
–
Comments should explain the why instead of the how or what.
In other words, your comments should not repeat what the code is saying. Code Complete uses these two examples:
//set product to base
product = base;
//loop from 2 to "num"
for ( int i = 2; i <= num; i++ ) {
//multiply "base" by "product"
product = product * base;
}
System.out.println( "Product = " + product );
//compute the square root of Num using the Newton-Raphson approximation
r = num / 2;
while ( abs( r - (num/r) ) > TOLERANCE ) {
r = 0.5 * ( r + (num/r) );
}
System.out.println( "r = " + r );
Both code snippets don’t look good (i.e. the variable names are bad). However, only the latter’s comments are useful, and the former would be better off with no comments at all.
–
If the code is so complicated that it needs to be explained, it’s nearly always better to improve the code than it is to add comments.
There are many ways to do this, ranging from using more descriptive variable names to inserting white space when needed. My personal favorite is to extract methods.
... //get user input ... //process user input ... //format and display output ...
In this case, the programmer crammed all of the logic into one function. This usually happens when the developer reached his state of “flow” and just keeps on typing hundreds of lines of code into the system. The problem with functions longer than a couple of dozen lines is that not only is it hard to read, it’s also hard to debug.
By extracting the logic of the comments, we can have clearer code without even using comments, not to mention an easier to debug program:
public void run() {
getUserInput();
processUserInput();
displayOutput();
}
private void getUserInput() {
...
}
private void processUserInput() {
...
}
private void displayOutput() {
...
}
–
And yes, this is post is a lame excuse for trying out the SyntaxHighlighter plugin. 
Anyone who has taken a software engineering course or has experience in developing software for clients should be familiar with the diagram above. It’s the infamous waterfall model, the approach in software development where projects are split into distinct phases connected serially to each other.
What most developers, managers, and clients who blindly use the waterfall model don’t know is that the 1970 paper that introduced that model (without naming it)–Dr. Winston W. Royce’s “Managing the Development of Large Software Systems“–is ironically a criticism of the model. Zooming in on the text below the diagram:
The rest of the paper then tries to provide possible ways to mitigate the risks involved in the model. I personally don’t agree with some of his recommendations, but this paper is almost 4 decades old so I’ll let them slide.
–
I am not saying that the waterfall model is a useless approach to software development. It actually a “best practice“; there are some projects that are better off done using the waterfall model or its derivatives.
As expected from best practices, however, people tend to think that the waterfall method is the best way to produce software regardless of context. I’m fairly confident that this misuse of the waterfall model is the root cause of most failed software projects. Thus, it is imperative that software developers should be familiar with both the risks involved with the waterfall model, as well as the alternatives to the waterfall model in case the risks are too high.
As a follow up to Cargo Cult Thinking and Best Practices, I’d like to share a story used by Dave Thomas (one of the authors of The Pragmatic Programmer) in a keynote Angry Monkeys and Cargo Cults.
I first heard this story from Neal Ford’s presentation on ways to improve your code. Fortunately, the presentation is a short run down of his book The Productive Programmer and this allows me to copy-pastequote the book instead of having to narrate it using my own words.
Back in the 1960s (when scientists were allowed to do all kinds of crazy things), behavioral scientists conducted an experiment where they placed five monkeys in a room with a stepladder and a bunch of bananas hanging from the ceiling. The monkeys quickly figured out that they could climb the ladder and eat the bananas, but every time the monkeys got near the stepladder, the scientists would douse the entire room in ice cold water. You can guess what that generated: angry monkeys. Soon, none of the monkeys would go near the ladder.
Then the scientists replaced one of the monkeys with a new monkey, who had not been subjected to the blasts of water. The first thing he did was make a beeline for the ladder, and all the other monkeys beat him up. He didn’t know why they were beating him up, but he quickly learned: don’t go near the ladder. Gradually, the scientists replaced the original monkeys until they had a group of monkeys who had never been doused with cold water, yet they would attack any monkey that approached the ladder.
The point? In software, lots of practices on projects exist because “that’s the way we’ve always done it.” In other words, because of angry monkeys.
Here’s some data on a major U.S.-based retailer used an example in The Halo Effect:
According to the report of independent industry analyst, Alex. Brown & Sons, during the early 1990s, “Qual-Mart” did these things:
- Installed point-of-sale terminals in its stores, which provided better information on sales by item and improved the inventory planning process.
- Expanded central buying to 75 percent of its merchandise, helping to reduce the costs of procurement.
- Modernized its inventory management and thereby significantly improved its “in-stock position.” One result: better management of seasonal inventory, boosting Christmas and Halloween sakes by 60 percent.
- Conducted physical inventory counts more frequently, not just once at year-end, resulting in greater accuracy and efficiency.
- Reduced its expense levels as a percentage of sales.
- Improved its merchandise assortment to match current demand trends, helping to raise sales.
- Installed a toll-free customer service number which led to a sharp improvement in customer satisfaction.
- Implemented a sophisticated client/server technology that led to better merchandise management and savings of $240 million.
Thanks to these many steps, “Qual-Mart” saw an improvement in inventory turns–that is, how many times in a year it sold its inventory, a key measure of retailing efficiently–from 3.45 in 1994 all the way to 4.56 in 2002. That’s a jump of 32 percent, not bad at all.
Then the book asks:
Would you say “Qual-Mart” improved its performance?
GTD advises those that practice it to empty their minds often. If you suddenly get a great idea or if just remembered something that you must do, you have to write it down somewhere as soon as that comes into your head. Not only will it be less likely to be forgotten, it will also free your mind to think about stuff that you actually enjoy thinking about.
The problem with this advice is that most of those ideas pop up when you’re on the go, and thus requires you to bring a portable note taking tool with you always. Ticklers or small notebooks are often too bulky to fit in your pocket, while PDAs and smartphones are often too expensive for such a simple task.
Enter the Hipster PDA.
The Hipster PDA (Parietal Disgorgement Aid) is a fully extensible system for coordinating incoming and outgoing data for any aspect of your life and work. It scales brilliantly, degrades gracefully, supports optional categories and “beaming,” and is configurable to an unlimited number of options. Best of all, the Hipster PDA fits into your hip pocket and costs practically nothing to purchase and maintain. Let’s make one together.
Technical debt is an important fundamental concept in the software engineering world, mainly because it pops up quite often in most real-world software projects. As much as I’d like to put the concept in my own words and sprinkle some personal experiences on it, Steve McConnell already wrote two good posts on the topic last year.
The term “technical debt” was coined by Ward Cunningham to describe the obligation that a software organization incurs when it chooses a design or construction approach that’s expedient in the short term but that increases complexity and is more costly in the long term.
Ward didn’t develop the metaphor in very much depth. The few other people who have discussed technical debt seem to use the metaphor mainly to communicate the concept to technical staff. I agree that it’s a useful metaphor for communicating with technical staff, but I’m more interested in the metaphor’s incredibly rich ability to explain a critical technical concept to non-technical project stakeholders.
Technical Debt and Technical Debt Decision Making [from 10x Software Development]
Some people, when confronted with a problem, think “I know, I’ll use regular expressions!” Now they have two problems.
- Jamie Zawinski
Some people, when confronted with a problem, think “I know, I’ll quote Jamie Zawinski!” Now they have two problems.
- anon
Just to show that I practice what I preach, I headed over to TopCoder a few hours ago to try my hand at some simple TCHS problems. By my surprise, the problem I opened was very similar to one of the technical interview questions in my previous company. I know this because as a technical interviewer, I’ve already given this problem to a couple of potential employees.
Now this isn’t surprising. Basic algorithm-related questions are good filters for weeding out so-called “developers” who never really had much programming practice in college, but there’s only a few types of questions you can ask at this level–go any higher and you’ll likely be stuck with Complicators instead of pragmatic programmers.
Anyway, what struck me with this problem is that it can also be solved with regular expressions. This has never occurred to me before, mainly because I didn’t expect even the top students from the top universities in the Philippines to approach the problem that way. From my experience, I would expect applicants to play around with loops instead.
This made me ask myself the question:
If you were a technical interviewer, how would you rate an applicant who used regular expressions in solving the problem?
Recent Comments