Timeline for How to document the high-level structure of a Java program?
Current License: CC BY-SA 3.0
7 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Mar 27, 2014 at 13:41 | comment | added | Doc Brown | @Onno: IMHO one of the most important high level diagrams are data flow diagrams - and after almost 20 years of UML, those kind of diagram type is still missing (and no, activity diagrams are no replacement for that). Instead, UML contains a whole lot of waste no one really needs or understands because the semantics is not clearly defined. That's why I don't like it when someone answers such a question with "use UML" as a knee-jerk reflex. Don't get me wrong: some parts of the UML are fine, and one can surely use them, even for high level docs. | |
| Mar 27, 2014 at 13:34 | comment | added | Onno | @DocBrown ok :) There are a lot of people that use UML just for drawing, but in my view you can achieve a good situational overview of your design if you have a proper understanding of the whole UML toolkit. Sometimes I get the idea that people see using UML to make a proper design as wasted time, looking at is as just a drawing toolkit. I have many experiences to the contrary, but you are correct that UML could have a better way of expressing itself in some of the diagram types. OTOH, many people think they know UML if they can globally read a class diagram, which is not true if you ask me. | |
| Mar 27, 2014 at 13:29 | comment | added | Doc Brown | @Onno: this was a little bit ironic of mine, but I think UML has only limited support for such a "high level" description, and a very unclear semantics. But I guess using package diagrams will be ok here (as long as the UML tool will allow to draw classes within packages). | |
| Mar 27, 2014 at 13:16 | comment | added | Onno | @DocBrown Why would UML be a bad solution in this case? | |
| Mar 25, 2014 at 21:41 | comment | added | Kat | @DocBrown UML is certainly not the tool for every job. However, if you're modeling something that fits the pattern of one of the UML diagrams (for example, modeling class relationships), then UML does offer a format which readers are likely to be familiar with, and familiarity eases readability. | |
| Mar 20, 2014 at 18:47 | comment | added | Doval | +1, Code examples of common tasks is the first thing anyone trying to learn an API is going to want. Javadocs and some description of the relationship between classes will fill in the blanks, but are not sufficient. | |
| Mar 20, 2014 at 18:38 | history | answered | Robert Harvey | CC BY-SA 3.0 |