Documentation in Software Development and Architecture

eleks.com

Agenda

• Documentation • What is good documentation• Tooling• UML• Other

Documentation way back then…

• Readme.txt • Comments in code• 1-2 diagrams

Documentation way back then…

• Booch diagram

Documentation way back then…

Documentation way back then…

• Jacobson use case

Why modelling

• Visualize the entire system• Easier to communicate• Understand roadmap• Reduce risk

Diagrams now

UML

Structure diagrams..emphasize the things that must be present in the system being modeled. Since structure diagrams represent the structure, they are used extensively in documenting the software architecture of software systems.

Class diagramDescribes the structure of a system by showing the system's classes, their attributes, and the relationships among the classes

Component diagramDescribes how a software system is split up into components and shows the dependencies among these components

Composite structure diagramDescribes the internal structure of a class and the collaborations that this structure makes possible

Deployment diagramDescribes the hardware used in system implementations and the execution environments and artifacts deployed on the hardware

Object diagram - obsolete Object diagram could be considered as instance level class diagram which shows instance specifications of classes and interfaces (objects), slots with value specifications, and links (instances of association).

Package diagramDescribes how a system is split up into logical groupings by showing the dependencies among these groupings

Behavior diagrams

..emphasize what must happen in the system being modeled.

Since behavior diagrams illustrate the behavior of a system, they

are used extensively to describe the functionality of software

systems

Activity diagramActivity diagram is UML behavior diagram which shows flow of control or object flow with emphasis on the sequence and conditions of the flow

State machine diagramState machine diagram is a behavior diagram which shows discrete behavior of a part of designed system through finite state transitions.

Use case diagram describes the functionality provided by a system in terms of actors, their goals represented as use cases, and any dependencies among those use cases

Interaction diagrams

.. a subset of behavior diagrams, emphasize the flow of control and

data among the things in the system being modeled

Timing diagramTiming diagrams are UML interaction diagrams used to show interactions when a primary purpose of the diagram is to reason about time.

Sequence diagramSequence diagram is the most common kind of interaction diagram, which focuses on the message interchange between a number of lifelines.

Communication diagramCommunication diagram is a kind of UML interaction diagram which shows interactions between objects and/or parts (represented as lifelines) using sequenced messages in a free-form arrangement.

Interaction overview diagramInteraction overview diagrams provide overview of the flow of control where nodes of the flow are interactions or interaction uses

UML Problem

UML is too technical for non-technical people but not technical enough for technical people

WHY PEOPLE DON’T USE UMLDon’t know the notationUML is too complexNever took a UML classInformal notations do just fineArchitecture documentation not deemed important

WHY PEOPLE USE UMLIt’s the standardTool supportUML is flexibleUML models are portableJust Need a Subset of the NotationArchitecture is important

Self-documenting code

XML Documentation

Naming things• Use names to explain the purpose of variables, functions, etc.• Avoid using vague words like “handle” or “manage” – handleLinks,

manageObjects. What does either of these do?• Use active verbs – cutGrass, sendFile. Functions actively perform

something.

Extracting functionsif(!el.offsetWidth || !el.offsetHeight) { }

function isVisible(el) { return el.offsetWidth && el.offsetHeight; }

…

if(!isVisible(el)) { }

Introduce a variableif(!el.offsetWidth || !el.offsetHeight) {}

//Instead of extracting a function, we can also clarify this by introducing a variable:

var isVisible = el.offsetWidth && el.offsetHeight;If (!isVisible){}

Tools available - Visio

Draw.io

• Cloud-based• Rich integration• Free

Gliffy.com

• Cloud-based• Rich integration• Free• Commercial for full

experience

Mind Jet Mind Manager

• Tool for mind maps

Sparx Enterprise Architect

• Tool for proffesional project documentation

Inspired by Technology.Driven by Value.

Find us at eleks.com

Have a question? Write to eleksinfo@eleks.com