What programmers gain from design?

Question

We all can write some program code and just design the solution in our heads. Also when we maintain existing code, we can see the design from the code if it is well written. Many people see documenting as an unnecessary burden that mainly causes extra work because the documents need to be updated too.

The other option is that we first create design documents, then program the solution according to the design, and later keep updating the documents. We might use separate designer to create the design documents or we can design by ourselves.

What programmers gain from design? Or is it alright to go and start programming without separate design documents? What are design documents needed for from the programmer's perspective?

Answer 1

If you are expected to finish quality software on time, you would need to get some requirements on paper before the coding begins. For business applications, writing every detail and confirming it with the domain experts avoids wasting time because programmers made wrong assumptions.

Answer 2

For any but the most trivial software, you must do upfront design otherwise you will either

A.) Fall flat on your ass B.) Have buggy software C.) Have a serious refactoring problem later on

In my opinion, the human brain glosses over facts that it is not willing to cope with at the time. In the case of software design, I always design upfront to make sure that I have something on paper that I am confident will work, and is optimally concise, functional, extensible, etc.

Answer 3

Programmers require at least some information before they can begin a project, whether this comes in the form of design documents or through direct contact with the people who need the software is obviously debatable.

I for one am in the agile camp, where people and interactions are favoured over process and documents. However, I am also pragmatic, which means if you do not have access to the business or product owners, then you must of course work to some design. But I will always favour having personal interaction over documents.

From the agile perspective (depending on your flavour) the documents, will be in some form of story cards which represent individual pieces of functionality to be developed and when that functionality is considered "done". The specific details of what is developed however comes from interacting and communicating with the business, and will be in most cases formed through 'evolutionary' design.

Whilst it is true that documents can be updated, and yes sometimes this even happens, I find that most times that this is not the case. You also run into versioning nightmares, developers working to the incorrect document, or QA testing the incorrect version. It is a simple fact that, in a fast moving business situation, as soon as you write it down it becomes out of date.

Most of the issues are unknown at the time of design and are discovered through the actual process of development, so it therefore makes sense to put more time and effort in the development phase than spending it during a design phase where assumptions can and will be incorrect. You can NOT design for something you don't know! The sooner you get in and 'discover' these unknowns, the sooner you can evolve your design to meet the new requirements.

Answer 4

For (very) small projects, programmers may be able to get by without much designing in advance. However, the larger the project becomes, the more important up-front design becomes.

You can build a doghouse without too much planning, but imagine building a skyscraper without architectural plans.

Large projects built without up-front design quickly degenerate into masses of unmaintainable code.

Answer 5

A mistake inexperienced programmers do, is to neglect the design part. They think it is lost time, but it is not. On the contrary!

A good design reduces by lot the work afterward. Including the bug finding.

Answer 6

Do not mistake "architecture documents" for "design documents".

As stated in this question, design is what it takes to implement architectural decisions, which can be stated as specifications document at business or application level.

When it comes to technical level, it is possible to establish "design" documents (UML diagrams, for instance), but they need to be kept in sync with development at all time, which can be hard to do.

The usual "design documents" I see are class diagrams retro-fitted from the code.

Answer 7

As well as things mentioned above, a design - for example a class diagram - can help give you the big picture. As your project gains more classes or modules, their roles can start to become fuzzy and it is tempting to just slot things in all over the place. If you keep the design up-to-date, it can help re-enforce the intended roles and help the programmer place things more appropriately, and avoid over-complicated and possibly circular dependencies. Similarly, a flow diagram can help keep us focused on how the parts should interact.

Answer 8

I believe that design documents are necessary. One reason for that is that you don´t have to waste so much time to introduce a new member to the project by letting him/her read the code. Instead the new member can take a quick look at the design to get the big picture.

Another reason is that if you do your design up-front (don´t forget to iterate) you will most likely find many of the bugs in the design phase which is less expensive to "repair" than if you find it in the development/code phase. You are more likely to find better solutions to your problems if you design up-front (with iterations). It´s easier (in my opinion) to get a coworker/project member to review your work if they don´t have to read the code, just a design document (UML diagrams etc...).