Here we go again.
I had a short talk today on how to document design.
I make now a short resume of the ideas.
All designs needs to document (from a perspective of a single software component) two main areas:
- static description
- behavioral description
For the first one, you need to imagine what is the layout of your SW Component (functions, variable, global or not). Let's call this class diagram. Additional, you have to catch in one picture which are the provided interfaces and which are the required interfaces. Let's call this component diagram.
If you imagine an engine, until now you depicted the size, shape and how the engine can be mounted in the car.
Then, please think about the behaviour of the SW component.
Imagine some scenarios based on use cases. This can be depicted using sequence diagrams.
Go further and describe special algorithms via activity diagrams. Don't use for each and every flow, it makes it only hard to read.
If you model your system based on states, don't forget state machine diagrams. Here, there is plenty of literature to read about modeling system based on state machine diagrams.
Here you go, takes this steps and try to document your work. Jack Ganssle makes a nice review on a new book, about documenting software. It goes in the idea of writing beside code. Al Stavely’s new book, “Writing in Software Development,”
I will come up next month with some ideas about how to mix Doxygen and tools like UMLet to make nice documented SW components.
Read More...
I had a short talk today on how to document design.
I make now a short resume of the ideas.
All designs needs to document (from a perspective of a single software component) two main areas:
- static description
- behavioral description
For the first one, you need to imagine what is the layout of your SW Component (functions, variable, global or not). Let's call this class diagram. Additional, you have to catch in one picture which are the provided interfaces and which are the required interfaces. Let's call this component diagram.
If you imagine an engine, until now you depicted the size, shape and how the engine can be mounted in the car.
Then, please think about the behaviour of the SW component.
Imagine some scenarios based on use cases. This can be depicted using sequence diagrams.
Go further and describe special algorithms via activity diagrams. Don't use for each and every flow, it makes it only hard to read.
If you model your system based on states, don't forget state machine diagrams. Here, there is plenty of literature to read about modeling system based on state machine diagrams.
Here you go, takes this steps and try to document your work. Jack Ganssle makes a nice review on a new book, about documenting software. It goes in the idea of writing beside code. Al Stavely’s new book, “Writing in Software Development,”
I will come up next month with some ideas about how to mix Doxygen and tools like UMLet to make nice documented SW components.
Postări
