For my next project, I’m looking to document my Object Oriented design in simple text before jumping the gun to code it up. I want to do this for two reasons.
- I want to give proper thought to my design and possibly revise it several times.
- I haven’t exactly decided which language I want to implement my project in.
I’m looking for a convention to outline my design in simple text, instead of a UML diagram. I like the convenience of text. I can version control it and easily put in a blog or wiki to share it.
I am thinking something concise e.g. how you might code in Python. However, I want the representation to be language independent. I’ve looked around the internet but couldn’t find anything. The closest would probably be how properties and methods are defined in the box representing a class in a UML Model.
Update:
I just wanted to clarify “in Text”. My goal is to be able to outline the object model in a github wiki. I imagine it being kind of an open source design in addition to code. Thus, I can create a Wiki page per entity and identify the relationships using links and formatting etc. However, what I wanted suggestions on was how to outline the specification of an entity on its page.
4
You could write in HTML and use hyperlinks to express relationships between different classes. The problem, though, is that you can’t see links. When documenting a design, the relationships are a big part of what you’re trying to explain, so it won’t do to make them invisible.
I’d suggest forgetting about plain text. Use HTML at a minimum, and don’t be afraid to include pictures created in your favorite drawing/graphing tool. These may not be quite so universal as plain text, but you’ll still be able to view them in any browser, and you should still be able to track them in a version control system just fine.
3
We had a huge project and I documented all of the teller functions using Use Cases.
So we had Deposit, Withdrawal, etc… with each one it had several local, mid, and backend processes to go through. At various levels I also had access changing by security. The use cases made all of that quite clear and allows you to document not only the system but also the players involved. Helps in determining what areas you need to design class libraries for and what different security comes into play.
That high level view makes it very easy to a) document what is happening — as well as — b) identifying potential sub systems you need to design/construct. It will, in the long run, make your next level of design much better (IMHO).
2
The closest things to what you want are Use Cases. These represent a textual representation of the requirements, ideas and design of your application.
A simple explanation can be found here at wikipedia.
However, for best documentation I recommend Alistair Cockburn’s Writing Effective Use Cases book.
1