Naming the pieces
Very important in an architecture documentation is to define and name the constituting pieces of the software.
From fine grained to coarse grained pieces
It is of central importance for everybody in the development team(s) to know how to name the composing parts, and to understand the boundaries and size of modules, subsystems, systems and components - if these are the names used in the architectural definitions.
Antido uses the following definitions:
- System
A system can be seen as an assembly of subsystems, equivalent to a deployable artifact in the Java EE specification.
- Subsystem
A Subsystem is a coarse grained software module that can be reused in different systems.
- Module
A module defines a different aspect of a subsystem. Sometimes it make sense to split a subsystem into minor parts, like separating implementation from interfaces, test and remoting code.
- Component
Component is the term most often used by different technologies in the Java EE world. It is only used to reference components of other technologies.
Orthogonal naming
After naming the pieces acording to their granularity, it is a best practice to use a name pattern to group similar subsystems/ modules.
Antidoto uses the maven groupId to group artifacts and a short acronym in the artifactId (the main name of the subsystem) as orthogonal naming convention:
- ti: technological infrastructure subsystem
- doc: documentation subsystem