9

I'm taking on my first enterprise-level application.

The truth is that I've always skimped in this department and I've never really modeled an application before. What is the standard way to do this? What type of diagrams should be used and what would the documentation look like?

When searching I can find numerous things around the net but I wanted to see if there is a current modern consensus on how to go about doing this.

17
  • 6
    You want to do waterfall? May 31, 2011 at 18:49
  • 1
    @Etienne, waterfall? If that's some sort of snarky reference then I'm not getting it. Constructive criticism/suggestions is appreciated. How about instead of upvoting a useless comment, you add your own comments to help me understand the issue.
    – user13280
    May 31, 2011 at 18:51
  • 7
    "I want my team to model the entire ASP.NET MVC C# application before we even tap out one line of code." Hate to say this, but you're almost committing yourself to failure before you even start. The full scope of usability, user requirements, maintainability are totally invisible until you start actually writing code; if you insist on a big design up front, you're going to spend much much more time updating your designs than writing your application. High level designs are ok, but documenting the entire app? Absolutely not.
    – Juliet
    May 31, 2011 at 18:53
  • 3
    @Chevex: Waterfall is a method of development that involves lots of up-front design. It seems quite accepted in the software development community that this method of development works poorly at best. May 31, 2011 at 18:58
  • 1
    touche @Chevex ,touche ... quietly walks away
    – mcgrailm
    May 31, 2011 at 19:51

5 Answers 5

8

a current modern consensus

The truth is: currently, that is something that modern software development is lacking - a consensus about modeling. UML seems to be some kind of least common denominator, but in reality there is only consensus about the notation, not about the semantics. There exists dozens of different opinions on how UML should be interpreted to create code (perhaps you can find one interpretation that is ok for your team).

On the other hand, there is some debate going on between people saying "don't make formal models, better write working code" and people who are thinking tools like "MDA" (model driven architecture) are the solution.

Other people (re-)discovered flow based programming for modern software design as a modeling alternative. Read here and here to find out more about that. According to my personal experience, data flow modeling has proven itself to be the most useful modeling tool I had used over the last decades, with a clear semantics and the possibility to switch between different levels of abstraction.

0
8

I want my team to model the entire ASP.NET MVC C# application before we even tap out one line of code

The problem that I usually find with such an approach is that my understanding of the solution is always incomplete at the beginning. It is only through refinement as work proceeds that I come to a final solution.

Trying to design the entire app up front, before any code (in all but the very simplest of apps) is usually folly.

Do you really believe you can lay out every class and method and data structure in detail in advance?

I just want to know some good modeling solutions.

As for actual tools to make models, I've tried a few and always end up back at Microsoft Visio.

Of all the products I've tried it seems the most straight forward and, actually, stable (my experience with modeling tools is that they are very buggy). To be fair, I do very little modeling, so take this recommendation with a grain of salt.

EDIT: Actually, I should say that most of my modeling is done on a notepad that sits on my desk. Because I do little modeling, I try to keep it light and to the point. Sketching out a diagram with pen and paper is much more efficient for me than using software.

You may find hand-written diagrams useful to form your ideas, prior to laying them out in a diagramming software.

What type of diagrams should be used and what would the documentation look like?

Most of what I model these days are interaction diagrams. Again, I don't do much modeling - just where I really feel the exercise of drawing the model helps cement my understanding.

8
  • We can adjust our modeling as we go. That's not the point anyway, I just want to know some good modeling solutions.
    – user13280
    May 31, 2011 at 18:52
  • So you intend to try and keep your models and code in sync. This does not work for most. They will inevitably diverge, and the discrepancies will cause problems. Plus you will spend large amounts of time trying May 31, 2011 at 18:55
  • Please read the updated question.
    – user13280
    May 31, 2011 at 18:58
  • @Chevex: I added all I could in regards to your edited question. May 31, 2011 at 19:04
  • @qes, my point was that you are answering a question I did not intend to ask. See the "UPDATE" section of the question.
    – user13280
    May 31, 2011 at 19:09
3

UML diagrams are a good place to start, there are many easy ways to do this with free or paid software. One simple example of a tool to make a UML is something like google docs drawings, more advanced packages would be Visio or OmniGraffle.

EDIT: As mentioned by many, if you were to go down the UML path, that doesn't mean you have to fully model everything, but you can come to a consensus about what you're modeling, and how detailed the models need to be. Simple UML diagrams can often help lay out your code before writing it, and clear up some potential issues before they arise.

7
  • I have heard of UML. Have any recommendations for a place to get started? Any good tools you recommend?
    – user13280
    May 31, 2011 at 18:51
  • @Chevex - just did a quick google search, and found this: agilemodeling.com/artifacts/classDiagram.htm Looks to be a decent starting point
    – Brett
    May 31, 2011 at 18:52
  • @qes - Depending on how much time/interest/investment he has in going down a path like this, it could be both a good learning experience and maybe help him understand some of the pieces of his code before he writes it (even if its just a simple UML)... But I do agree, he should probably have sufficient time and personal interest in doing this.
    – Brett
    May 31, 2011 at 18:57
  • @qes, please read the updated question.
    – user13280
    May 31, 2011 at 18:58
  • 2
    @Chevex - You probably want to start by doing some reading on the diagram types, and what they are intended to communicate. UML is a modeling language which can be very descriptive, but also has a lot of nuances. UML in a Nutshell helped me out quite a bit (oreilly.com/catalog/9781565924482). That being said you can often get by with pared down versions of the full diagram set. As long as the people creating the diagrams and the people reading the diagrams agree on what they mean.
    – ckramer
    May 31, 2011 at 18:59
2

As @Brett suggested, UML diagrams are best. With UML its good to have Class diagrams and work flow diagrams. These two would cover most of design needs.

With the class diagram you can model the members of each entity, their security level etc.

With work flow diagram, you can model which method call which calls, what's the result of work flow and what would be exception that can possibly pop out.

2
  • Thank you for this answer. Recommend any useful tools? Does visual studio support UML in any way?
    – user13280
    May 31, 2011 at 19:01
  • Visual studio provide help for doing a class diagram. Its not good for workflow. Rational tools are best for such UML design/modeling. Rational software modeler is what I am familiar with. I have heard that Rational rose would be another great tool.
    – SaravananArumugam
    May 31, 2011 at 19:03
2

While I strongly believe in making some basic architectural drawings before writing code, I think that making a detailed drawing of the entire app is too much work.

I usually create a few outline pictures in Visio, often using the "flowchart" building blocks to visualize what I mean. Using UML often feels to formalized and invites to too much detail. The Visio drawings show the basic building blocks of the application and which type of functionality goes where. If you are using the MVC framework you are mostly done just by taking a sample drawing off the web and copying it.

A good idea is to make a few drawings from other points of view. Instead of drawing everything, I often prefer taking one specific function of the system and then visualize it as:

  • Use case diagram (UML)
  • Flow chart or UML Swim-lane (very high-level)
  • Architectural component overview.

Then we start coding. While coding I'm using doxygen with the dot integration to get on-the-fly class diagrams, inheritance etc. Viewing the doxygen generated overview is often a very good way to see the code structure.

0

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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