0

I am working in a purchasing system where we take calls:

public class Call 
{
    public List<CallItem> CallItems { get; set; }
}

The calls can be turned into quotes, where call items become quote lines:

public class Quote
{
    public List<QuoteSegment> QuoteSegments { get; set; }
}

public class QuoteSegment
{
    public List<QuoteLine> QuoteLines { get; set; }
}

And quotes can be accepted and turned into orders, where the quote lines become order lines:

public class Order 
{
    public List<OrderSegment> OrderSegments { get; set; }
}

public class OrderSegment
{
    public List<OrderLine> OrderLines { get; set; }
}

There are many transitions like this in our system, where one item can become another. The relationships between their attributes is not always obvious. It becomes time-consuming to read the code and try to trace through the flow of information.

Is there a suitable type of diagram, UML or otherwise, that can be used to show the in-depth relationships between two classes? So that I can show exactly which Call attributes map to which Quote attributes, which Quote attributes map to which Order attributes, and so on?

Sydney Park
  • 19
  • 2
  • 2
    I would use state chart diagram https://www.tutorialspoint.com/uml/uml_statechart_diagram.htm or https://www.researchgate.net/figure/UML-Statechart-describing-the-possible-states-of-a-Sales-object_fig1_29749961 However, I prefer creating a spreadsheet of object states and which business conditions moves the object from one state tot the other. UML is not very good for every possible case. – NoChance Jul 02 '19 at 20:57
  • 2
    Side thought (not sure if it's applicable) but have you considered a different design which doesn't need these kind of "turns into" relationships between attributes or makes them clear by self-documentation? Maybe `CallItem`, `QuoteLine` and `OrderLine` could share a superclass? Maybe the `Call`, `Quote` and `Order` classes could be combined into a single class but with a `Status` attribute (mutable or immutable variations of this)? Or maybe the different classes have to be separate but all of the attributes which map could be named identically? – just me Jul 02 '19 at 21:23
  • 1
    You need to separate business analysis information from code. In real life systems, things get so complicated that self-documenting code that reveals rules can't exist. Business rules should be documented as such. Object design should not change to make rules clear. Object design should be made to make the system correct and efficient not clear. – NoChance Jul 02 '19 at 22:32
  • 1
    If the goal is to make it easier to mentally keep track of what's going on, I would just list the properties of one object on the left, and of the other on the right, and make a map (e.g., connect the corresponding properties with arrows); hopefully things can be arranged/reordered so that it's not a messy web of tangled lines. You might also be able to extend the map several levels to either side, if that's helpful; if that's not possible, you could make several separate diagrams. – Filip Milovanović Jul 03 '19 at 01:26
  • 1
    Looks like a mapping from one type to another (not state change). If you would introduce mapper per "transition" it would be obvious enough what types can be converted to other types. – Fabio Jul 03 '19 at 02:21
  • @NoChance, _Object design should be made to make the system correct and efficient, not clear_ - Object design can be made correct, efficient and clear. You just need to choose your threshold of tradeoff. – Fabio Jul 03 '19 at 02:22
  • State Diagrams have those semantics. You can lift those and any other notations you need. @NoChance At the very best of times a Human might be able to keep 7 points actively in mind. A skilled practitioner can make that number seem much higher because they have managed to abstract a simple model, and know when to not trust the abstraction. Code is the designed solution, and often that covers more than 7 decisive points - so an implementation is rarely clear. The best we can hope for is that the code guides your thought process to that high level abstraction, with obvious caveats. – Kain0_0 Jul 03 '19 at 05:30
  • Isn't that what DFDs are for? – Stop harming Monica Jul 03 '19 at 07:13
  • @Goyo, DFD's are not part of UML and are not meant to show state change. DFD's show data flow. – NoChance Jul 03 '19 at 10:06
  • @NoChance UML is not a requirement and I don't think "becoming" is to be interpreted as state change since an instance of `Call` can't become an instance of `Quote` by means of a state change. – Stop harming Monica Jul 03 '19 at 11:37
  • Are you missing some other key domain class like Product or Service? That is, your calls, quotes and orders are really about products/services. Your question is lacking concrete details (to me) along those lines -- it is hard to reason about abstract quote lines, for example. As for a diagram, I would say that an Activity Diagram would make it pretty clear that during some process, a Quote is consumed and an Order is produced. – Fuhrmanator Jul 04 '19 at 12:50

3 Answers3

3

You need to step away from the word "becomes" and maybe rethink your domain language.

In the code a Call object can't "become" a Quote object. My guess would be you create a new Quote based on the data from the Call and persist both of them to a db with a relationship. Maybe a shared key.

You can UML that up no problem because they are all operations common to programming languages and have representations in various design schemes.

Trying to make you design fit the domain language is a good idea, up to a point. Continuing to use the domain language when it is misleading is a bad idea.

For example, if I get a quote from you and then send a letter asking for a cheaper one; the Quote does not become a call and which is then updated and becomes a Quote again. You probably go back to the original Call and generate a new Quote. so you have 1 call and 2 quotes.

Ewan
  • 70,664
  • 5
  • 76
  • 161
2

The main point of a diagram is to convey information. Exactly how it does so is usually a secondary concern. UML and other common types of diagram give us a shared diagrammatic language, but there's no reason you can't invent a type of diagram, as long as it says what you mean.

I'm not aware of any standard diagram format that conveys what you want out-of-the-box, but personally I'd approach it starting from something people are likely to know (in this case maybe a UML class diagram) and adding extra elements wherever that's helpful, doing my best to make it clear. I've heard these referred to as "UML-like" diagrams.

What about something like this? example UML-like diagram

just me
  • 628
  • 4
  • 9
  • Class Diagram is not meant to show state. What "becomes" is dependent on a condition? UML provides a statchart diagram as in my comment above. – NoChance Jul 02 '19 at 22:29
  • @NoChance I would respectfully disagree that the state machine diagram (as I know it) fits the question, which was asking how to show the links between attributes in different software objects which represent the same conceptual data at different points in a real-world object's lifecycle. If you can represent that on a state machine diagram, I'll upvote your answer. I think this (which isn't a class diagram, it incorporates two of them plus other stuff showing correspondence) fits Sydney's requirement but I'm open to discuss what you feel it lacks. – just me Jul 03 '19 at 16:25
  • Thank you for you feedback and polite response. You are correct the "state machine diagram" may not be the best for this case. However, the links I have provided display what I think would work. – NoChance Jul 03 '19 at 17:44
  • Thank you for your answer. It might not be the most graceful, but solves the problem in a way that someone would instantly recognize what they are looking at. I suppose I was unclear with my wording and created some confusion about the word "becomes," but you got it spot on. I want to show what parts of one object are used to inform another object's attributes. I think I will be using this. – Sydney Park Jul 11 '19 at 16:40
0

I would use an activity diagram:

enter image description here

As for your question about links between Quote and Order, it might be easier to understand if your domain model described what items are as Products or Services. If a Call/Quote just has "lines" or "segments" it's very abstract. If a call concerns products, which have prices, quantities, etc. it makes it easier to convert into an order.

Fuhrmanator
  • 1,435
  • 9
  • 19