Improving the Code through Installation Manual Analysis

What can you learn from your install manual that can make your product better?  Below I outline a technique to work through an existing installation manual, and methodically find clues on how to make a software product better.

Timers: Common Misunderstandings

At some point you will be asked to implement a timer — something that displays the amount of time that is elapsing.  It can be a count-up timer showing the total times that something has been happening.  Or it might be a count-down timer showing the amount of time remaining to complete a particular task.  Most programmers will make some key mistakes the first time they attempt this.  I am rather shocked and amazed at how many incorrect examples you can find if you scan the internet.

Advertisement

Classic Date Drift Case Study

A waterfall project is required to predict dates that certain things will happen in the future.  There are usually many pieces of the project, each with their own date, and each dependent upon others.  No one can change a date without effecting others, and so a game of “chicken” ensues where people report dates they plan to complete and never hint there is a problem.  At the last possible minute they declare a change in date, and when you look at the history, you can easily conclude that they should have known ahead of time that the deadline was to be missed.  But everyone waits for someone else to change first.

Growing Software like a Plant

Maybe it is helpful to view the development of a software in using an Agile approach as being like way that a small tree grows.  In contrast, development of software using waterfall is like that of a factory.  The difference between a tree and a factory tells us a lot about the difference of these two styles of software management.

Complex Projects need Agile MORE than Smaller Projects

I met another Japanese executive last week who said “An Agile approach may be fine for other projects, but our software is big and complex, and because of that we have to use Waterfall approach.”  This is the exact opposite from the truth:  the larger and more complex the code, the greater the need for an agile, iterative approach.

Don’t Fear Rewriting New Code

The last post #28 Avoid “Test Script” Fever was about simplifying an implementation that was more elaborate than it needed to be.  There was a waterfall-style project in exactly this situation, and leader responded saying “It has already been coded the other way, and if your goal is to save programmer time, rewriting will just waste more time.”   No, it won’t, and this post explains why.

Two is Not Better Than One

In software design you often must choose between two competing approaches.  Which is better?  It is tempting at times to say “Let’s do both, and let the user choose.”   That might be good, but there are many cases where that is a serious mistake.

#26 Don’t add Methods and Classes that you don’t need.

This should be obvious, but it is a rule that is violated quite often. This is one corollary to the YAGNI (You Aren’t Gonna Need It) Principle.    This post discusses that there is a proper time to do things, and it is a waste to do them ahead of time.

#19 Reduce Cognitive Load

Deeply nested IF statements can be hard for the brain to unwind and process correctly.  In many cases, the branch statements are selecting for a single, or a small set of conditions for which processing will be done, and outside of those conditions nothing will be done.  Given this, the code can be structured to avoid complexity, make it easier to understand, and less costly to maintain.