Introduction
Software design helps me understand and resolve problems before they are manifested in code. While designing I use plenty of diagrams, some of which are shown below. Some pointers are given to tools you can use and when they are appropriate.
The overview
Show the components in play, gray out the less important ones. Keep names as specific as possible, ie. use postgres over database, unless that component can be dynamically replaced.
Use image maps to link components to more detailed instructions, e.g. for graphviz
dot -Tcmapx graph.gv
Work more freely with automatic preview using xdot
xdot -f dot graph.gv
Graphviz source: all.gv
Serviced - component details
Details could include interfaces and or packages depending on size.
Graphviz source: serviced.gvService - class diagram
Show relations between structs (classes) and the important methods. Good when designing data and expected behaviour. Don't cram in every detail, just what is needed to convey a certain feature.
Graphviz source: service.gv
Middleware - sequence diagram
Use sequence diagrams to illustrate important paths in your callstack.
Mscgen source: middleware.msc
State diagram
Pipelines and states transitions in your applications are best visualized with state diagrams.
Graphviz source: state.gv
Color scheme
Choose one and stick with it. Remember black and white goes a long way.
Graphviz source: colors.gv
References
- mscgen - sequence diagrams
- Graphviz node shapes
- ud - inline output in html