In January, 1998 I received a great variety of insightful comments from readers on the software development process and the goals of design, the subject matter of my first Design Techniques article, which is published in JavaWorld. I plan to base Chapter 1 of Flexible Java on the material from this article that focuses on design goals.

Thanks to all those who submitted comments. On this page, I have reprinted, with permission of the authors, selected comments from readers.

The main topics of the comments reprinted here are:

• The advantages and dangers of using a prototype in lieu of a specification.
• Ten practical guidelines to keep in mind when starting the design phase of a new project.
• The kind of fame that clever code will buy you.
• A vote of confidence on the technique of postponing method implementation.
• Using regression tests instead of stepping through a debugger, and the importance of peer reviews.
• Moving beyond the waterfall method, the importance of project planning abilities, and a call for UML.
• A few comments about the monkeys.
• A voice for analysis.
• My own comments regarding the feedback.

Ten practical guidelines to keep in mind when starting the design phase of a new project.

Hi,

I have read your article about Introduction to "Design Techniques".

The article gives in brief a good idea of the all picture.

It is necessary to emphasize that at the start of the design several actions are recommended:

1. Understand how the customer works, his needs, his expectations from the new software.
2. Define & declare standards such as coding techniques, documentations of code, which documents are needed and their table of content.
3. Think big, start small. Try first the implementation on a small project, learn from the mistakes and then dive in to the major project.
4. The helpful design questions: What? Where? When? Why? Who? How?
5. The rule that is always being ignored: "Keep it simple & stupid"
6. Don't try to make the solution to solve all the user problems, set priorities with the customer, separate the project into several phases.
7. Involve the customer from the begriming, good for promoting the project, and good to ensure that the project meets the customer needs.
8. First do the infrastructure, which will dramatically speed the later coding development.
9. Don't invent what you can buy from the shelf.
10. A good project design also plan & design the testing.

The kind of fame that clever code will buy you.

It seems some programmers believe that clever code will earn them the respect and admiration of those who later read it. In truth, the opposite is true. You will be despised for your clever code and honored for your simple, easily understood code.

Matt Gerrans
mgerrans@ix.netcom.com

A vote of confidence on the technique of postponing method implementation.

"Bill has hit upon something I've always tried and practiced, but have seldom been able to get others in my team practice. The point about documenting the DESIGN in code w/o implementing methods is something every software developer must practice and every software manager should encourage and support !!"

Nash Aragam
naragam@acm.org

Using regression tests instead of stepping through a debugger, and the importance of peer reviews.

"This is by far the best short introduction to Java-based software design I have ever read. Bravo! I have a couple of suggestions.

First, the idea of unit testing via stepping through a debugger is inconsistent with the the iterative nature of modern development. This is because it is way too time consuming to do every time you touch a class implementation. This means it is only done (if at all) after initial implementation. While it is certainly useful, we have found that designing simple, automated regression tests that exercise each method in a class on simple input to be more effective. Even if the tests do not exercise the class thoroughly, they can be run after every modification to the class (or as an integral part of the release process). My experience is that even the simplest of automated tests is much more effective at maintaining software quality in an iterative environment than any manual testing method (even if much more thorough), simply because any manual method is so labor intensive that it just doesn't get done due to those other "monkeys".

Second, the role of peer reviews in improving quality, readability, and maintainability cannot be overstated. I conjecture that high quality software is typically the result of a small group working together and regularly looking at each other's work products. (I believe it is much more difficult for an individual working alone or a large group working together to achieve either the same level of quality or the same level of productivity as is possible with a small group.

Keep up the good work with this series. If the remaining articles are as good as this first one, they will be referenced for a long time. "

Anonymous

Using regression tests instead of stepping through a debugger, and the importance of peer reviews.

"Well-written article. While I imagine that the "process" you describe is well beyond what most software shops are actually doing these days, I would caution that it is not close to the ultimate place we want to be headed. For example, there are many more and much better methods (formal or otherwise) than the simple waterfall method you describe. A quick read of _Debugging the Development Process_ or _Rapid Development_ will give you some great insight into what could be done in this area. (sorry for the MS bias here, but they *are* good books :-).

One other point that often gets overlooked is the importance of good project planning abilities. While this is crucial for a project lead (and rare, I might add), everyone on the team benefits from knowing how to read and contribute to a decent GANTT chart.

One last comment. I would disagree that javadoc is an adequate design tool. Again, a day or two learning and playing with UML will make the world a better place for all of us. While I appreciate that the existing tools out there are horrendous (how can experts in software design methodologies show their faces in public when their company makes such a piece of trash?), even a tool like Visio, or MacDraw will suffice in the right hands, and produce a picture that is worth a thousand lines of code. Remember that some of us think more visually, some more aurally, some textually. Good communication of design should contain all of these. Anyway, I hope you take my criticism as it was intended (constructive ;-) and I look forward to continuing a dialog."

Carl A. Dunham

A few comments about the monkeys

So you are saying that programming is really just the art of monkeying around?

Matt Gerrans
mgerrans@ix.netcom.com

"I've been designing, implementing and developing software for years, and when I read your article this morning, I saw all those monkeys materializing right there. Your article is a good abstract of what we (developers) should maintain as "mantra" to destroy those monkeys, and develop good object-oriented, or not, software."

Elderclei Regis Reami
reami@intermidia.icmsc.sc.usp.br

I think I'll have nightmares about monkeys. :)

D. Orlando Keise
dokeise@cymen.com

That was a great article. The reader is able to associate well with the "monkey" analogy for the problems and requirements that arise in a project. However, I have a question in terms of project schedule. When we work as contractors, there is very little flexibility in terms of time to execute the project. In such cases there is always a tendency to by-pass procedures. Would you have any suggestions on how this can be addressed?

L. Ravindranath
ravinath@hclt.com

A voice for analysis

[...] The only thing I found a little disturbing is the suggestion to use the Javadoc tool as a design documenting tool. As I understand, you need to have the classes defined in order to use this tool, and through the intial phases of a design, I would expect to see an architecture model, a data model, a business (functional) flow model, and I'm not sure these can be done with the Javadoc at such an early stage, when you're not suppose to have the whole class structure in your mind. What do you think?

Sarah Shporen
sarah@netmedia.net.il

My own comments regarding the feedback.

First, I 'd like to say that I don't consider myself an expert on the software development process. (The remainder of the articles in this column won't be about the development process, but rather will focus on nuts and bolts design techniques.) I have, however, learned a thing or two about what process works well for me over the years. What I wanted to write about last month is what I've learned through my own experiences in the cubicle. I think the feedback reprinted above helps to broaden nicely whatever light I may have shed on the development process in my article.

The main point raised by the feedback that I would like to address here is the absence of any mention of analysis from my article. I must now confess that I left off any mention of analysis from my first article in part as an experiment to see how many people complained. To my surprise, only one person brought it up, Sarah Shporen.

I have had one major experience with a project that had a formal analysis phase. I was working on a project with a team of approximately 20 members. The code of this project was to be implemented in C, and management had us follow a Yourdon-Constantine approach of structured design. This project had an analysis phase of drawing bubble charts (data-flow diagrams) followed by a design phase of drawing structure charts. Only after the analysis and design phases were completed did we begin coding (the implementation phase).

The idea of this approach was to first do an analysis of the solution domain in an abstract manner, without worrying about dividing the system into processes and figuring out how those processes would communicate. After we'd completed the bubble charts of the analysis phase, we converted them into structure charts for the design phase. In the design phase we did worry about processes. We made a separate structure chart for each process, and each box in the structure chart directly represented a C function in the solution.

My experience was that this process worked quite well. It was a good fit for that particular project. I personally found the data flow diagrams and structure charts were a nice way "structure" to the thought process of designing software that was going to be implemented in C. Also, in this project we had enough time to be methodical, because the hardware for which this software was being written was way behind schedule.

However, in most projects I have worked on, the schedule pressures were far more intense. In most projects, a formal analysis phase was not part of the process, and the team managed OK without it.

It may be that my experience is skewed a bit because I have done consulting. It could be that companies call on consultants the most when projects are already well behind schedule. But what I've seen is that development speed is usually the single most important deliverable. That's why I made the "meet the schedule" monkey the one with its arms around the developer's neck. It is also why I try to use UI prototype code in the product to the extent possible, and to express the design in code that is missing method implementations. I do these things in the name of speed.

The other way I am biased is that for some reason, I have never found the formal object-oriented methodologies to be as useful as the structured methodologies I encountered while working in C. When I was first starting in object-oriented programming, I attempted to mine insights from an O-O process book written by Grady Booch, but I personally found it to be too abstract. This turned me off to formal O-O methodologies, and I ignored them for a long time.

These days I am trying to give formal O-O methodologies another chance, and am learning UML. I do like the line from Carl Dunham's comment, that "a picture is worth a thousand lines of code."

Thanks again for all the feedback.

Bill Venners
bv@artima.com