4

During the design stage, I usually come up with a class diagram that looks something like this

Sample from Lucidchart

However, during coding stage, I would never create a class like Librarian with issueStatus() or searchBook() method.

100% of the time, class Librarian, will be a plain-old-object with only getter and setter method, and issueStatus() or searchBook() functionality will be implemented in a class of it's own (possibly class IssueStatusActionHandler or class SearchBookActionHandler, which will be triggered by user action (e.g clicking a button)

Does this mean that I have to include the software architecture during the design stage, or do I need to revise my class diagram documentation in parallel with coding?

Short answer
  • 59
  • 1
  • 3
  • I think your class diagram isn't. It looks more like a use-case diagram with shorthands for particular uses disguised as methods. If you create a use-case diagram, Librarian and Patron appear as actors, that carry out processes like `search for a book` and `request a book`. From there you can use the pattern "Use Case Becomes A Class" to create classes such as "SearchForBook" and "CollectPayment". – BobDalgleish Nov 09 '16 at 17:04

3 Answers3

4

It highly depends on your goal of what to achieve with your design.

As it seems, you are not targeting a code generator that directly translates your class diagram into code. Hence, the diagram is just that: a pretty picture. You may want to first rethink the actual value you get from it and why you are making the effort. Contrast that to scribbling out the diagram on a whiteboard with your colleagues and once you're all satisfied, take a photo. What's the big difference?

As for your questions: Do you need to include architecture in the design stage - we'd hope so. The whole point of architecture is to be a framework into which you fit your design considerations. So clearly, you will have to take it into account.

Do you need to revise your diagram during code? This again depends on why you have that diagram. If you want it to describe your code, then obviously it needs to be revised. If all you need is to be able to tell people "look, this is how we envisioned it three years ago. Nothing in the code is anything close to that now though" then feel free to neglect it.

Should you however have a need for an up-to-date UML diagram, then I strongly suggest to move closer to actual modelling (as opposed to simple drawing) such that you can generate code and therefore ensure that the diagram is really corresponding to your code.

Finally a remark on your "100% of the time" way to write your code: While this has nothing to do with your actual questions, I urge you to reconsider your idea of writing business logic (like issuing a status) into action handlers. This violates many good design principles. If you like to read, you may want to take a look at the DDD book by Eric Evans to get a better idea of how business logic like that is served better.

Frank
  • 14,407
  • 3
  • 41
  • 66
  • (Fix) It might interest to the OP [Anemic Domain Model anti-pattern](http://www.martinfowler.com/bliki/AnemicDomainModel.html). Related @Frank last suggestion. – Laiv Nov 09 '16 at 07:38
0

During the design stage ... However, during coding stage ....

First up, let's address your confusion here. Writing code is design. So what you are doing isn't "design" then "code", it's all design.

Whether UML is ever useful is questionable, but some like to use it to help them visualise possible solutions. As "Uncle Bob" puts it in his "Agile Software Development: Principles, Patterns, and Practices" book:

So, yes, diagrams can be inappropriate at times. When are they inappropriate? When you create them without code to validate them, and then intend to follow them. There is nothing wrong with drawing a diagram to explore an idea.

If you follow the good practices of using TDD and iterative development, then it's pretty much guaranteed that the code will differ from any UML drawings you create. As an added bonus, you are less likely to end up with business logic in event handlers and the like. Such poorly differentiated, tightly coupled code rarely develops out of using the TDD approach.

As to what to do about the fact that the two differ, you have two choices:

  1. If you can, treat the UML as a brainstorming/whiteboarding exercise and throw it away.
  2. If you are required by some contract or process to produce UML though, then run your code through an automatic UML generator to produce those diagrams. And try to change your company culture to remove the need to do this.
Community
  • 1
David Arno
  • 38,972
  • 9
  • 88
  • 121
  • 1
    The problem here is the OP does not follow "the good practices of using TDD and iterative development", he is clearly trying a waterfall approach (cough), with trying "high level design" (what he calls design) and "low level design" (what he calls coding). And he is experiencing that his UML diagrams don't match his code, either. P.S. I did not downvote you. – Doc Brown Nov 09 '16 at 10:00
  • 1
    @.DocBrown, I suspect you are right. I'm likely giving sprinting advice to someone who's not quite worked out how to walk yet :) – David Arno Nov 09 '16 at 10:17
0

Coming up with designs(in this case the UML) helps one to visualize how the code will eventually become.It does not make worth to have a class with its methods which cannot be translated into code.In short what you have on the paper should match the code. Methods such as SearchBookActionHandler should be included in the design of the class unless you have some cases of inheritance which still can be interfaced,but still have to appear in your UML.And of software architecture being in the design stage...Yes it should be factored.

wanjiku
  • 19
  • 3