Sequence Diagrams

Sequence diagrams show interactions between objects over time. Actors are external entities that interact with the system, shown as stick figures. They represent users, external systems, or devices that initiate or receive messages. Actors are placed at the top or sides of the diagram and have lifelines extending vertically. Each actor represents a role rather than a specific individual, making the diagram applicable to multiple scenarios.

Objects (or lifelines) represent class instances participating in the interaction, depicted as rectangles with dashed vertical lines (lifelines) descending from them. The lifeline represents the object's existence over time. The rectangle shows the object's name and class, typically in the format 'objectName : ClassName'. If the specific instance name isn't important, you can omit it and just show ': ClassName'. The lifeline is a vertical dashed line that extends downward, representing the passage of time from top to bottom.

Objects can be created during the interaction (shown with a creation message) or destroyed (shown with an X at the end of the lifeline). Creation is indicated by a dashed arrow pointing to the new object's rectangle. Destruction is shown with a large X at the point where the object ceases to exist. This notation helps visualize object lifecycles within the interaction, including when objects are instantiated and when they are garbage collected or explicitly destroyed.

The diagram reads from top to bottom, showing the chronological order of messages. Time flows downward, so messages at the top occur before messages at the bottom. This temporal ordering is crucial for understanding the sequence of operations. The horizontal positioning of lifelines doesn't imply any spatial relationship—it's purely for readability. You can arrange lifelines to minimize message line crossings and improve clarity.

Activation boxes (thin rectangles on lifelines) show when an object is actively processing a message, helping to visualize call stacks and concurrent execution. An activation box starts when an object receives a message and ends when it finishes processing. Nested activation boxes show method calls within method calls, helping to understand the depth of call stacks. These boxes are optional but provide valuable information about object activity during the interaction.

Sequence diagrams use different arrow styles to indicate message types, each with specific semantics. Synchronous messages use solid arrows with filled arrowheads, indicating the sender waits for a response before continuing. This is typical for function calls where the caller needs the result immediately. The receiving object processes the message and returns control to the sender. Synchronous messages are common in procedural code and blocking operations.

Asynchronous messages use open arrowheads, meaning the sender doesn't wait for a response. The sender continues processing immediately after sending the message. This is common in event-driven systems, message queues, or when operations can be performed in parallel. Asynchronous messages enable non-blocking communication between objects and are essential for modeling concurrent systems. They're often used with callbacks, promises, or async/await patterns.

Return messages are shown with dashed lines and open arrowheads. They indicate the response to a synchronous message. Return messages carry data back to the sender and mark the completion of the synchronous call. In some diagrams, return messages are omitted for simplicity, especially when the return value isn't important to the narrative. However, including them improves clarity about the flow of control.

Create messages use dashed lines with open arrows to show object creation. The arrow points to the new object's lifeline, which begins at that point. Create messages are used when objects are instantiated during the interaction rather than at the beginning. This helps visualize dynamic object creation patterns and factory methods.

Destroy messages use X symbols on lifelines to indicate object destruction. The X is placed at the point where the object is destroyed, and the lifeline ends there. This notation is important for understanding resource management and cleanup sequences. Found messages come from unknown sources, shown with open arrows from the diagram edge. They represent messages that originate outside the scope of the diagram, such as external system calls, user inputs, or timer events. These messages help identify system boundaries and external dependencies.

Sequence diagrams support several control flow constructs that represent complex logic. Loops repeat a sequence of messages, shown with a rectangle labeled 'loop' and a guard condition in square brackets. The loop fragment encloses the messages that repeat, and the condition specifies when the loop continues. For example, [i < items.length] indicates the loop repeats for each item in a collection. The condition is evaluated before each iteration, and the loop exits when the condition becomes false.

Alt (alternative) fragments represent if-else logic, divided by dashed lines with conditions. Each section represents a different branch of the conditional. The first section is the 'if' branch, subsequent sections are 'else if' or 'else' branches. Only one branch executes based on the condition. The conditions should be mutually exclusive to avoid ambiguity. If no condition is specified for the last section, it's treated as the 'else' case.

Opt (optional) fragments show optional sequences, equivalent to if without else. The fragment executes only if its condition is true. This is useful for representing optional steps in a workflow. Break fragments exit the loop prematurely when a condition is met. They're similar to 'break' statements in programming languages and help model early termination scenarios.

Parallel fragments (par) show concurrent execution, divided by dashed lines. Each section represents a concurrent thread of execution. The diagram shows all sections executing simultaneously, which is useful for modeling parallel processing or multithreaded systems. Parallel fragments help identify potential race conditions and synchronization issues.

Nested fragments allow complex logic to be represented hierarchically, with loops containing alt fragments, or alt fragments containing loops. This nesting captures real-world complexity where conditions exist within loops, or loops exist within conditional branches. These constructs allow complex interactions to be represented clearly. Proper use of control flow constructs makes sequence diagrams expressive enough to capture real-world interaction patterns. However, avoid overusing fragments as they can make diagrams cluttered. Use notes to explain complex conditions or assumptions that aren't clear from the notation alone.

Effective sequence diagrams follow these guidelines to communicate design intent clearly. Use them to document critical interactions or complex workflows, not every possible message flow. Sequence diagrams are most valuable when explaining runtime behavior, error handling, or complex algorithms. They're less useful for simple CRUD operations where the interaction pattern is straightforward.

Keep diagrams focused on a single scenario or use case. A diagram trying to show multiple scenarios becomes confusing. Create separate diagrams for different use cases or variations of the same use case. For example, create one diagram for successful login and another for failed login attempts. This approach makes each diagram easier to understand and maintain.

Name lifelines clearly to indicate their role in the interaction. Use descriptive names like 'userSession' instead of generic names like 'object1'. Include the class name to show the type of each lifeline. This helps readers understand the participating objects without referring to other documentation. Consistent naming conventions improve readability across multiple diagrams.

Include return messages for clarity, even if they're optional. Return messages show the completion of synchronous calls and help visualize the call stack. They also clarify which messages expect responses and which are fire-and-forget. Omitting return messages can make diagrams ambiguous, especially when showing complex nested calls.

Use notes to explain complex logic or assumptions. Notes can clarify business rules, error handling strategies, or design decisions that aren't obvious from the diagram. Place notes near the relevant messages or fragments. Avoid overloading diagrams with too many lifelines (ideally 3-7). Large diagrams with many lifelines become difficult to read. Consider creating multiple diagrams for different subsystems.

Consider creating multiple diagrams for different scenarios within the same use case. This helps stakeholders understand various paths through the system. Review diagrams with developers to ensure they accurately represent implementation details. Developers can identify potential issues or optimizations that might not be obvious from a high-level design perspective. Update diagrams as the implementation evolves to keep documentation current and useful.