Tech Answer Blog

Documentation should be a pre-coding activity — documentation is a detailed design of what you are going to build, i.e. a blueprint for the program in human-readable language that describes the technical details of the program.   Adding in documentation after a program is written when no specification or design exists for the program is a futile effort, since most programmers could interpret and produce the same documentation from the code itself.   If a non-trivial condition discovered during maintenance is exploited in a certain block, however, that would warrant notation in the code.   Suppose a repair found that a special condition that was commented out needs to be uncommented out.   You’d want to note why it remains uncommented so that future programmers think twice before commenting it out again.   That might look something like this:

// uncommented: X might not be less than zero when condition ABC happens in module 123
if X<0 then ...

First of all, there are general translation errors that can result in code errors based on misunderstood requirements.   This causes some issues, but the majority of issues come from cultural differences.   In India and some other countries, it is considered disgraceful to say “no” to a boss, so certain groups have a tendency to say “yes” to something that they don’t really understand.   I had to work with a group of Korean offshorers that also had this problem.   In order to get something done correctly, you had to set it up in such a way that they could learn or ask questions without seeming like they were saying they didn’t know how to do it.   Businesses that don’t take this into account will pay lots of money into offshoring and get absolutely nothing worthwhile back out, other than a bunch of “yes,l understand” and then about 5 lines of code that don’t do anything.

From one of my Indian friends:

I totally agree with you Devin. Saying “no” to your boss in India is considered as asking for trouble.

Many “experts” are now on some strange vendetta against GOTO and GOSUB; each has convincing-sounding reasons why these commands shouldn’t be used for various reasons in computer programs.   Rather than argue for or against these reasons, I will simply present the following fact:   GOTO and GOSUB work fine if you have designed your program to use them.   However, if you haphazardly use GOTO and GOSUB to skip around in a program, they can cause problems.   They are neither always bad or always good, just as any programming construct can be abused, but I would not discourage anyone from using one if it makes sense to use… provided that you understand how they work (obviously, it’s the same rule with any programming construct).

The moral: a poorly designed program will have errors of all kinds, including GOTO/GOSUB abuses.   A well-designed program, however, can use these commands without logical or architectural penalty.

Devin

(Notes) Note subdesign elements requiring additional research, test cases or proofs of concept (poc’s). Make sure to do these items first and factor results or limits back to design or requirements as necessary, to prevent/minimize issues. Example: Main design > sub design 1 (with its own requirements, design research, design and code, test, etc). Note limitations of sub design with respect to feasability of main design, based on reliance of main design on the subcomponent.
1. Are there impacts to the current requirements based on the design? For example, do the requirements cause feasibility issues in design? If so, send these impacts back to requirements phase. The project parts that are not impacted may continue forward, but the release should be adjusted to account for additional necessary changes. If not, then the release can be expected to have a number of predictable problems, costing significant time and money overages as compared with an appropriate design-time adjustment.

2. Research design limitations for workarounds and risks thereof. If there are limitations and risks, send these back to requirements as necessary.

3. Analyze design for overly complex or elements in need of a design refactor, note for phase two, or implement changes to design before coding.

These are the questions that have to get answered in order to successfully deliver a software engineering project, in whole or in part, by an individual or team.

Phases: Requirements, Design, Config, Code, Test, Rollout, Troubleshoot, Other

Requirements questions:

1. Do you have all the requirements collected? If not, collect some more from whomever can supply requirements to you or the team. If there are any unanswered questions re: the existing requirements, then you don’t have all the requirements yet.

2. Are the requirements strong, firm and understandable, and agreed upon in writing by the supplier? Having the requirements in writing is the only way to guarantee that all parties have had a chance to comment on the requirements as they are understood by the developers. If this step is not taken, feature creep will plague your project.

3. Are all the risks for the given requirements spelled out and accounted for? For example, if there is the risk of a project overrun based on an especially difficult requirement, then make sure this is spelled out in the requirements document. If it is not written down, then the client can easily say that they didn’t know the project would cost more or go over. It is the responsibility of the engineering team to make the client aware of these issues up front whenever possible, or to at least indicate where there may be issues, if the issues are not yet entirely apparent.

4. The project should be able to move to the design phase, provided that all of the above questions are answered sufficiently.

If you plan before acting, you will have a much higher probability of catching mistakes before they actually happen.   I recommend planning out any complicated activity, listing options and possible side effects, before taking action on a project.   The plan becomes the documentation for what was done, so in case something does actually go wrong, the steps to reproduce the problem are apparent.