Last week I announced my new project idea called Jungle Dragon. After such an announcement, my natural tendency is to start coding as soon as possible. I mean, why not? Very few developers enjoy documenting a design. Since I'm the only developer on the project, why would I document anything but the code itself?

The answer is: size. And complexity. The functional and technical base of Jungle Dragon is too large to fit in my boney head. I might be able to fit it in, but I'd lose sleep over it. I tend to apply the "Just Enough Design" principle to my work, which essence comes down to scaling the need for design and documentation to the size and complexity of the project. In other words, design where it makes sense, in order to support the code base, not just as a project formality.

Having said that, I'll hereby take you on a short tour on how I'm applying this concept to Project Jungle Dragon.

Just Enough Design for Jungle Dragon

I've been thinking about project Jungle Dragon for months, at a conceptual, technical, and personal level. In order to capture my ideas and clarify the concepts and goal of the project, I've created a two-page project brief:

It may sound crazy to do this for a one-man project, but I disagree. When I'm at my lowest during the long development phase, this document will remind me of the goal of the project, and hopefully reinforce me. Plus, it kind of feels like a relief to put your thoughts on paper like this.

With the tiny project brief completed, it is time to make some high level implementation choices. I documented this in a one-page architecture diagram. In essence, it documents the main building blocks, choice of technology, layers and framework components. Like the project brief, this is mostly a one-time upfront effort that acts as a reminder.

Note that I try to make the design documents look good, and sometimes even brand them. I don't do this to show them of on my blog. Rather, it provides me a positive, yet serious association with the project. Plus, my girlfriend thinks they're pretty, although she probably does not even know what it is.

Up next is the functionality. A common industry method to design or document functionality is to make use of use cases. I like them for personal use too, but only if a project is of substantial size:

Note that I use the UML notation freely. Instead of connecting actors to use cases, I color-code them. Not to be a rebel, I do this simply because otherwise the document would become too messy. Don't worry about perfect UML compliance, the point of design is to get your idea across. In this case, the project has a lot of functionality. Without a use case overview, I would get lost pretty quickly. Plus, the use case is a nice starting point for the database model:

The database model is actually the first design asset that is not just documentation. This is the actual design of the database that will be used at run-time. Needless to say it is of crucial importance. It is my preference to visually design a database, print it out, and have it on my desk while coding. In my experience, this is also the design asset that changes the most, so don't worry if your first version is not complete.

Next is the class diagram:

There's much to say about class diagrams. First, some people prefer to first design a class diagram and then the database diagram (domain-driven), others prefer it the other way around (database-driven). Since this concerns a PHP project, I prefer to go for the database-driven method. Another consideration is the available tooling. When I develop in Visual Studio, I can visually design a class diagram and it will sync with the actual code, thus the design is actually part of the code. In the case of PHP, it is simply a seperate document.

One could argue to not create a class diagram for such a project at all. The reason I still do is that objects!=data, in other words...your objects may look different and have different relations than your database model. It also depends on the architecture of your application, you may not even use objects. In my project, the point of the class diagram is to document the model classes and their relationships. I do not bother to include all class attributes from the database model, as that would lead to a lot of duplicate work when the database model changes.

Phew. With that out the way, we can start coding, right? That's what I did. Full of confidence I started working on the user registration and management module. After a day of coding, I started to realize how complex it really is. I was not happy with the structure of the code, in fact I had trouble understanding it myself! Realizing my mistake, I went back into design mode, and documented the various user management routines:

I'm using UML Audit diagrams to document the flow, decisions, states and errors in the processes. With this clearly documented and thought out, coding the module itself becomes easy. Again, documenting this routine did not feel like a pain, it was more like a relief.

Concluding

So far for the little design tour of Jungle Dragon™. It is by no means complete, I'll likely add design assets as I go along in the project. Anyway, here is a short summary of my design tips:

• Design is not a goal in itself, it must support the project. Therefore, apply just enough design to the project as needed, no more.
• Try to use industry standard notations, but don't be afraid to deviate from them where it makes sense.
• Have the courage to admit a mistake, go back into (re)design mode and enrich your designs. Iterative design always wins from big, upfront designs.
• Care for your designs, make them look nice, understandable and friendly.
• Mentally position yourself to embrace designing as a relief, rather than a pain. You will automatically make this switch as soon as you have created some designs that really work for you, instead of against you.

BOOKMARK THIS CONTENT

	Bookmark at:

RATE THIS CONTENT (OPTIONAL)

	Was this document useful to you?
	Rating:	Awesome  Good  Average  Poor  Useless

CREATE A NEW COMMENT

	Name:
	Email:
	Website:
	Content:	HTML is not allowed. Hyperlinks will automatically be converted.