Category: Software Engineering

Developer Nomenclature

I might as well get this one out before I write other software engineering posts.

You might have noticed that I rarely use computer programmer when talking about people crafting software. This is simply because crafting quality software requires a lot more than knowing how to code programs.

Recall the waterfall model:

Waterfall Model

As mentioned in my post, it’s flawed, but only for its flow. The steps, from System Requirements up to Operations, are still applicable in the creation of all client-based software systems.

As you can see, Coding (or in technical terms, Construction), while still a very important part of software development, is just one of the seven steps in development. Of course it doesn’t take only 1/7th of the total project effort, but in practice it only takes 50-20% of the total effort: the larger and the less agile the project, the less effort is spent on construction.

That said, in the context of software development, the term programmer is sometimes used as a pejorative, implying that the person’s only job is to code programs based on designs handed down to him by Analysts or Software Architects. In other words, he’s just a grunt.

I personally don’t consider the term to be a pejorative, especially since I personally don’t mind getting my hands dirty with grunt work. So yes, I’m proud to be a computer programmer. However, I won’t use that term in my posts because, as I said above, it’s too narrow.

—

In place of “computer programmer”, you would see me use the terms software developer and software engineer interchangeably.

Both terms solve the problem posed by “computer programmer”, namely, that both titles span the entire software development life cycle. Software developers are not limited to computer programming. They can also be analysts that gather and process the user’s requirements, or architects that design from a much higher standpoint than analysts. They can also be in specialized roles other than programming like QA Testers and DBAs. They can even be Project Managers, a role that don’t have any direct relationship to the crafted system itself.

The only practical difference between the two terms is that some people shy away from software engineer because as it stands software engineering is still mostly a misunderstood buzzword rather than a serious profession. You have guys saying “I’m a software engineer!” but fail to grasp the basic concepts of software engineering from project management (e.g. Brook’s Law, Peter Principle) down to construction (e.g. basic OOP concepts).

But then again I’m unfazed by that concern. I’m still hoping that the day will come that our profession would be a lot more respectable than it is now, so for that dream, I’ll be using the two terms interchangeably.

Code Comments

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. :P

Waterfall Model

Waterfall Model

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:

I believe in this concept, but the implementation described above is risky and invites failure.

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.

Angry Monkeys

Go near that stepladder again. GO NEAR THAT STEPLADDER AGAIN. I dare you, I double dare you, motherfucker. Go near that stepladder one more goddamn time.

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.

Technical Debt

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]