Made in USA: Enterprise Application Services

software development practices Archives • Ayoka - Made in USA Enterprise Application Services


October 22, 2009

In software development, it is no great secret that things don’t always go according to plan. It’s a stressful job, to say the least, especially when things go wrong. I would not be at all surprised to learn that there exists a positive correlation between software development and rates of trichotillomania.

So what puts a project at risk, and how do we plan to deal with these risks when they occur?
Steve McConnell, the patron saint of practical software development practices, eloquently identifies some of the common problems that bring software projects to ruin.



As McConnell points out, in software development, optimism can be deadly. An optimistic, can-do attitude often leads to the creation of impossible schedules that puts projects at risk of failure. In order to mitigate this risk, it’s imperative that developers and managers alike adopt a healthy, pessimistic attitude. Plan for the worst and aim for the best. Don’t ever rely on luck or good fortunes to see your team through to the end. Optimism and hope is not a replacement for solid planning and risk management.


Software development companies often bow to the pressures of their clients and rush through the requirements analysis and design phases. This is always a mistake. Many studies show that the cost of repairing requirements mistakes outweighs the cost of repairing implementation mistakes by several orders of magnitude. Spend the time to get requirements right before starting even the design phase of the software. In the long run, it will save your company a bundle. And don’t take just my (or McConnell’s) word for it – there is plenty of plenty peer-reviewed research demonstrating the validity of these claims.


Gold plating occurs when developers and managers add features to software to make it “better.” This often occurs past the requirements and design phase, where the implementation of a new feature is far more costly than it would have been had it been planned out in the initial phases of the software’s development. Customers, developers, and managers alike are all responsible for this. Each stakeholder should take different steps to manage this risk:

  • Developers: it is the developer’s job to explain to managers what is possible and what isn’t. As most developers know, what seems like a simple change on the surface (adding a button that performs some nifty function) sometimes requires substantial modifications to a whole subsystem. Accurately estimate the difficulty of any proposed change and make sure that your managers are fully aware of what functionality may be placed at risk by the change.
  • Managers: it is your job to determine how important a change is to the software’s “mission” since they are the ones most in touch with the customer’s point of view. If the change is a convenience change, leave it out. It’s often tempting to add nifty little features toward the end of a project, but the road to hell is paved with good intentions. On the other hand, if the change is absolutely vital to the mission’s success, explain this to the developers so that they don’t take a morale hit from going back and rewriting old code.
  • Customers: customers are an integral part of the development team and the whole reason behind the team’s existence. It is imperative for project success that the developers know precisely what requirements they need to fulfill. Customers should review requirements documents carefully before signing off on them and not hesitate to point out any mistakes. Remember that misunderstood requirements cost tens to hundreds of times more than implementation mistakes.


Project managers sometimes fall into the trap of viewing software development as an assembly line process. It leads to the idea that if a project is behind schedule, adding more developers to the team will automatically bring the company closer to the goal.

This sort of thinking is horribly and fundamentally wrong.

McConnell cites a number of studies demonstrating that not only does adding developers at mid-to-late phase during a project not increase productivity, it actually detracts from it. The reason for this is simple: in any complex project, it takes time to bring a new developer up to speed on both the domain knowledge and the project architecture. Existing developers on the team must then spend some of their time fixing the inevitable mistakes made by the new team member and attempting to train the new developer.

So how do we manage this? The answer is fairly simple. Build your team immediately and then involve them at every phase of the project. A developer who was involved in the requirements analysis and the design phase will be more productive than a developer who is starting out with little to no knowledge of the project’s intricacies. Involvement is the key.


This risk tends to apply more to developers than to project managers. We’re a technology-loving bunch, on the whole, and so when a new framework comes out that promises to make our lives easier, we’re almost instantly ready to jump onto the bandwagon. So optimistic are we that we’ll gain productivity from the new technology that we revise our software cost estimates to reflect the expected productivity gains.

This is dangerous.

Although new technology often does increase productivity, it is not possible to predict the sorts of things that can go wrong with a new technology. It is also important to factor in time for training on the new technology, a facet of a developer’s job which is often underestimated.

While nothing is intrinsically wrong with trying new technology, it is important to be conservative with cost estimates when walking on uncertain ground. This ties in to the risk of optimistic thinking, outlined above.


There are many other common types of risk that fall well beyond the scope of a blog post. The important thing for developers and managers to do is to sit down with one another and draft a risk management plan. The trite aphorism is telling: if you fail to plan, plan to fail. Determine at the beginning of a project what might go wrong and how best to deal with the situation should it occur.

Following this strategy will result in better software for customers, lower costs of development, and fewer grumpy developers.

Commenting Your Code

October 6, 2009

Last week I was working with a Java library for manipulating SVG’s. With the library came a Javadoc, but when I looked through the Javadoc, I was surprised to find that none of the methods had any explanations. Classes were shown as well as the methods that belonged to each class. But what did doScale() do? What was the purpose of SVGAbstractTranscoder? None of this made sense, and while a “getting started” guide was provided, it wasn’t thorough and only explained a few simple tasks, none of which helped me do what I was trying to. Long story short, I had to move to a more well-documented library, and though it has less features, I at least could figure out how to use these features as the documentation was vastly superior.

Comments are immensely beneficial to anyone that is going to be dealing with your code, including yourself. There are many places where comments are helpful, including those describing a method, those describing class properties, those describing classes, and those describing the purpose of a block of code. Of those listed, I feel commenting a method is the most beneficial. Object-oriented programming (OOP) naturally tends to have many method calls across many different classes, and being able to find your way around and determine the expected input and output of a method, but also the purpose of a method can be a lifesaver. Even one brief sentence can help someone out that would otherwise have absolutely no clue what this method you wrote is for. Not only do comments help you later on down the road, after you’ve written the code and possibly forgot what a method was for, but it has the immediate benefit of making you think, “what is the purpose of this method?” If you comment methods before you write the implementation, you have a “definition” of the method, and when implementing your method, you’ll be able to tell if the purpose of the method is becoming fuzzy or if the code you’re writing is spot on with your original intentions of writing the method.

It is also important to note that most modern IDE’s have the ability to parse through comment blocks above methods and the better the comments, the better smarter the code completion will be. For the purists, some IDE’s allow you to throw errors at compile-time if a method is not commented, a feature that I sometimes find a burden, but more often than not has led to me writing better code than I would have otherwise.

Some feel that well written code doesn’t need comments, and some (I don’t get this logic) feel lots of comments are bad because it demonstrates that the code is not self-descriptive. This is just plain wrong, well-documented code rarely, if ever, means code is sub-par. In fact, I would go as far as to say the opposite is true, if I see good comments, I get that piece of mind that the author of the code knew his intentions well and planned out the code well enough to be able to define a purpose for each method, each class is carefully targeted and named for a specific purpose. If I saw a library with 500,000 lines of code, I would honestly be pretty scared of the stability and robustness of such a library.

Lastly, if you don’t want to take my word for it, look at any open source code library. I’d be willing to bet comments are poured liberally throughout the entire library. It’s not uncommon for the comment of a method to be longer than the implementation of the method. There is such thing as too many comments, but too much is better than not enough.

So, in conclusion, don’t be afraid to use comments, they’re your friend.

Music While You Code – A Distraction?

July 7, 2009

Several classes on software development practices will tell you that programmers are more productive in a quiet environment undisturbed by external forces. Distractions prevent a programmer from entering “The Zone,” which is a state in which the programmer is fully focused on the problem before them and its solution. Yet more than half of the developers that I know, myself included, listen to music while developing. Listening to music, even loud music, seems unable to inhibit a developer’s ability to enter the Zone.

From my own experience, listening to music while developing serves as a form of white noise. At times the office can be a noisy place, even if the noise is not directly connected to you. People discussing projects, the ringing of a phone. These and other sounds can serve as just enough of a distraction to interrupt a train of thought.

Listening to music, on the other hand, allows for me to mask these other sounds, and after listening to music for a while, my brain puts it in the background. More often than naught, I will have no idea what music has played while I’ve been coding or even realize that it has reached the end of my playlist. The music also serves as a good break from debugging hard to find glitches in code or when dealing with the quirks of software necessary to develop software.

I would be interested in hearing what other developers think of the issue. Is it a distraction or do you listen to music while coding for similar reasons?