Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I'm in my final semester of college and am taking a software engineering course. In the class we learn about various software development methods. The one we focused on, and used to develop our project, was the waterfall method.

I feel like the instructor may have implemented it wrong. In our class diagrams, we had to list ALL properties and methods including private ones. I have read a few books, namely Clean Code, that say to keep functions as short and focused as possible. It seems tedious to list every little function in our diagrams if they don't help other developers out (they're private, no one else will use them). Plus, I may not think of every tiny function when designing the program, they may come along when refactoring.

Did the instructor tell us wrong by asking us to list every function? And, do these design methods squash the developer's individualism to write code how they can best understand it?

share|improve this question
That's pretty bad that your class is teaching the Waterfall method, which is a canonical example of a bad processes for software development. – whatsisname Sep 6 '11 at 17:44
I'd say this class has taught you a lot. – JeffO Sep 6 '11 at 17:46
Actually, the original waterfall has iterations that feedback into each other. It's the incorrect teaching of Waterfall throughout the years that has destroyed it's usefulness. Even with something such as Scrum, the steps a Story goes through in a Sprint emulates that of a waterfall into itself. UML diagrams are only useful for high level design. As soon as the code is written any documents written before that code are now out of date. This is the realization of engineering. In the end, the code has to be the documentation. – Andrew T Finnell Sep 6 '11 at 17:50
Pretty much every developer has seen cases of developer's individualism that ought to have been squashed. (Though probably not by waterfall methodology). – psr Sep 6 '11 at 18:01
@whatsisname, I strongly disagree. Every developer should learn Waterfall development so they UNDERSTAND and EXPERIENCE it as a canonical example of bad software development. Further, many shops are still Waterfall for right or wrong and it is important that grads are prepared for that. – maple_shaft Sep 6 '11 at 19:27
up vote 10 down vote accepted

Did you ask the instructor why you had to list all the methods?

It is possible that, like with much of what is asked for in a classroom environment, the intention was not to make your class diagrams more helpful to developers but to help you and your classmates think about how you would design your classes. When students are learning how to decompose larger problems into smaller problems, it's probably helpful for them to think about what private methods they would likely need. And it's probably helpful for the instructor to get a better idea of what methods students are thinking of implementing in order to intervene earlier in the process if someone's design is poorly thought out. Documentation in a classroom environment is often much more involved than documentation in a real world environment because the instructor's intention is that writing the documentation forces students to consider things that they might be too inexperienced to think about if they are just focused on their code.

Of course, it is also possible that the instructor believes that this level of documentation is helpful in a real project. If that's the case, the instructor is probably either out of date or came from a particular niche background where this level of planning and documentation is appropriate. If you're building the navigation system for the space shuttle or designing medical devices, for example, it's generally far more appropriate to invest heavily in design up front rather than refactoring code during development. If you're developing a social networking site, on the other hand, a more agile approach is more appropriate.

share|improve this answer
+1 for pointing out how different design is needed for different purposes. Good points about class design also; asking the instructor is a good idea – Ethel Evans Sep 6 '11 at 19:02
Remember the rule for passing a college course: Find out what the professor wants, and deliver that. – Christopher Mahan Sep 8 '11 at 0:58

No, the instructor is right in telling you to list all the properties and methods upfront if you are using the waterfall method. Wikipedia notes a criticism of waterfall:

Many argue the waterfall model is a bad idea in practice—believing it impossible for any non-trivial project to finish a phase of a software product's lifecycle perfectly before moving to the next phases and learning from them. For example, clients may not know exactly what requirements they need before reviewing a working prototype and commenting on it. They may change their requirements constantly. Designers and programmers may have little control over this. If clients change their requirements after the design is finalized, the design must be modified to accommodate the new requirements. This effectively means invalidating a good deal of working hours, which means increased cost, especially if a large amount of the project's resources has already been invested in Big Design Up Front.

These design methods don't squash the implementer of the design's individualism as there are still parts to interpret and ways to put one's unique touches on the structure,e.g. picture given a skeleton and adding the muscle and other tissues to create an animal wondering how much freedom did you have to design that animal?

You have found a shortcoming of waterfall yes but everything has its strengths and weaknesses.

share|improve this answer

In the class we learn about various software development methods. The one we focused on, and used to develop our project, was the waterfall method.

You probably learned the classical Waterfall model, which the person attributed with introducing it to the software development world stated from the start was inappropriate for developing large-scale software systems. You would probably be interested in reading Winston Royce's paper titled Managing the Developemt of Large Software Systems to learn more about the problems with what many people consider to be the Waterfall model.

However, the Waterfall model is good for teaching the software development lifecycle as you go through and can spend time learning about and performing requirements engineering, architectural design, detailed design, implementation, testing, and maintance in very clear, distinct phases.

In our class diagrams, we had to list ALL properties and methods including private ones. I have read a few books, namely Clean Code, that say to keep functions as short and focused as possible. It seems tedious to list every little function in our diagrams if they don't help other developers out (they're private, no one else will use them). Plus, I may not think of every tiny function when designing the program, they may come along when refactoring.

These are all very valid points.

Listing all properties and methods during the design phase, even when using Waterfall, is probably overkill. You should definitely list everything that's public, along with the essential properties. In reality, everything else is an implementation detail that you can obtain by reverse engineering your implementation into diagrams.

Clean Code's advice (I've never read it - I'm just going by what you posted) seems to be fair, and applicable even when using the Waterfall methodology. You can design your classes and methods with respect to the Single Responsibility Principle, separation of concerns, and other principles of SOLID. Waterfall doesn't tell you how to design, just when you need to do it. That said, it is harder up-front as you learn and think of better ways to do it during implementation.

I think this points out the fact that there needs to be iteration between design and implementaion very clearly - a problem that traditional Waterfall doesn't account for.

share|improve this answer
+1 for the link to the paper of Royce. – pillmuncher Sep 7 '11 at 0:59
@pillmuncher So few people have read it, it's kind of sad. – Thomas Owens Sep 7 '11 at 1:23
The saddest thing about that paper is that most people actually discovered waterfall through it, while it's a paper that thoroughly discredits the practice. – Joeri Sebrechts Sep 7 '11 at 7:26

It seems tedious to list every little function in our diagrams if they don't help other developers out (they're private, no one else will use them).

If you think this is tedious, wait till you get a real job programming. Consider, for a moment, that software may not be a viable career for you.

Plus, I may not think of every tiny function when designing the program, they may come along when refactoring.


did the instructor tell us wrong by asking us to list every function?

No. It's a common requirement.

And, do these design methods squash the implementer of the design (the developer's) individualism to write code how they can best understand it?

Yes. The soul-crushing of individuals is an important part of software development. All individuality will be beaten out of all programmers at all times in all possible ways. It says that somewhere in the "God's Rules of Programming" handed down from some mountain to some prophet.

No. You're just balking at the tedium. Get over it and get back to work.

share|improve this answer
@FreshDaddy. "They (for the most part) won't ever see private functions." False. After you win the lottery, other programmers will take over your code and see the private functions. Also. Some languages (e.g. Python) eschew this kind of privacy. – S.Lott Sep 6 '11 at 18:16
@S.Lott - Listing every private function is not a common requirement at all. It happens, don't get me wrong, but a full-scale "list every private function before writing code" is certainly pretty rare. There is "necessary tedius" and then there is "worthless tedius". Considering programmers are in the business of eliminating "worthless tedius", real world clients would hardly ever request something as costly and pointless as this, unless it was "life or death" type code. – Morgan Herlocker Sep 6 '11 at 18:28
@ironcode: '"list every private function before writing code" is certainly pretty rare.' Not in my experience. It's how people learn to do design. Junior programmers are often held to this standard until they can prove that their work doesn't require this level of oversight. Generally less than a year. An organization that took n00bs from school and threw them at programming with no oversight is mostly just creating huge problems. This level of oversight is essential to be sure that code has a fighting chance of working. – S.Lott Sep 6 '11 at 18:48
@S Lott - my motto is that if software development is tedious, you are doing it wrong. We're programmers. We automate the tedium. We don't repeat ourselves in code, and there is no reason to repeat ourselves in the documentation either. – kevin cline Sep 7 '11 at 2:41
@kevin: this answer is pure sarcasm. As such, it is completely inappropriate, and I've flagged it. – Michael Borgwardt Sep 7 '11 at 8:24

Programming is the art of working within constraints. The CPU provides a limited instruction set; IO is constrained by the design of the hardware; OS APIs are created to encourage certain behaviors and restrict others; high level languages are often designed to promote one set of idioms over others...

And methodologies too are crafted to restrict.

Your challenge, in all aspects of the development process, is to realize your vision within those constraints. Will you bash your head against each wall thrown up by hardware, language, API, and methodology? Or will you find a way to harmonize what you wish to achieve with what is allowed and encouraged?

Do you really think your instructor wishes to read through endless pages of minutia? Then test that theory: break a program up, and document each atom. When his desk is sagging under the weight, I rather suspect you will find that his true desire is somewhat different from what you expect.

Or prepare the documentation as you see fit. Make it clear, make it understandable, make it read like a Dashiell Hammett novel. And then sit down and talk to him, show him what you've done, convince him of its merit.

share|improve this answer

I think the instructor is brilliant for making you do this project, and thus teaching you the pros and (mostly) cons of Waterfall development.

share|improve this answer

A simple rule of thumb to gauge project analysis complexity is "Can the developper or the company he works for can be held responsible for something dramatic enough (generally including death or huge amount of money lost) happening with the software created?".

I had the same experience as you for some of my courses. People who had a background in the miltary industry would teach us analysis. And that would be complete and exhaustive analysis, planning all the course of the project, even in the smallest details. You cannot afford much iterations with this kind of project (also bomb exploding can be ok, budget exploding are not), so no place for creativity here, you have to go by the plan.

On the other hand, if you have read a bit, you certainly read about agile methodologies. There is generally less documentation, and more room for the developper to use his creativity while developping a solution to the problem he does encounter.

In conclusion, the more experience you get, the better, and what your instructor is showing you does apply in some part of the industry. Just be aware that there are certainly as many way to manage and design a project as there are to code them. And you will find defenders and critics for all of them. Test them while you are studying, and choose the one you're happy with.

share|improve this answer
And be careful about "Can it kill people if it crashes" there's another type called "Can someone go to jail if this prints out wrong data" and that will often get back to the guy fingering the keyboard, so it's good to have very detailed requirements, to the smallest detail. – Christopher Mahan Sep 8 '11 at 1:07
@Christopher : adjusted my answer accordingly, thanks for the comment :) – Matthieu Sep 8 '11 at 12:27

Some software engineering classes, such as the one I had, are taught in a weird style where 'failure is success', success is a wasted opportunity to learn from failure, and more is less and less is more. If this is one of those, then just stick with the assignments and enjoy the weirdness.

share|improve this answer

I think your instructor is out of touch. Commercial software is rarely designed or documented to that extent. It's far too expensive, and the resulting documentation cannot be maintained without even more expense. IMO such practices are a legacy from days when coding was often done in assembly language. Your time would have been better spent trying more agile practices: test-driven development, pair programming, continuous refactoring.

Did the instructor "tell you wrong" ?

I think so.

Assigning boring work to intellectual property workers is wasteful. In school, boring work has little or no pedagogical value, except perhaps to inure students to boring work. Such exercises have negative consequences, both to the students, and to the industry. The students are harmed because their time is wasted. The industry is harmed, because some students may conclude that such tedium is necessary, and useful. It is neither. In thirty years in software, the only work I can think of that was both boring and useful was changing backup tapes. There were robots that could do that, but they were prohibitively expensive.

share|improve this answer
Dare I say you've never worked for a company that makes it's money from Government contracts. (edit) You did say Commercial software.. My statement is meaningless now. – Andrew T Finnell Sep 6 '11 at 17:48
@Andrew Finnel: The truth is so painful, on so many levels. – Peter Rowell Sep 6 '11 at 17:52
@Andrew - I have worked to DOD2167. It was horrible and unproductive as it was practiced. Later I worked for another company that is doing agile development for the government with frequent deliveries. The client is wildly happy. They had a useful application in six months and get new features quarterly. – kevin cline Sep 6 '11 at 17:57
@Andrew I have over 2 years of experience in US DoD work, as a government employee and as a contractor. Agile methods are being adopted. One team I worked on was actively using Scrum, producing "just enough" documentation "just in time". Yes, documentation (even "just enough" documentation) is significantly more extensive than many other places, but that's typically driven by the number of involved parties (contracts can change hands, other parties can develop other systems, and so on) and/or the safety or life criticality and importance of the systems being development. – Thomas Owens Sep 6 '11 at 18:01
@Andrew it's not just governments. I've seen 40 pages specifications for "products"; normally can you select everything from this table and give it to me pipe delimited please. No one can ever be bothered to read them... – Ben Sep 6 '11 at 18:29

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.