Architectural-Toolbox-Description.md

@@ -8,6 +8,33 @@ The toolbox is comprised of three tools: Arcan for Java systems, Arcan for C/C++
 The sections below provide further details on architectural smells and the role of each tool provided by this toolbox.
 
 # Architectural smells
+There are four types of architectural smells supported by the toolbox.
+*  **Cyclic Dependency**
+*  **Unstable Dependency**
+*  **Hublike Dependency**
+*  **God Component** (Java only)
+
+The first three types of smells are all based on the concept of dependency. By dependency we mean that an artefact `A' depends on `B' if it requires `B' to fulfill its functional requirements.
+These three smells are therefore detected on the dependency network of the system.
+God Component, on the other hand, is detected using the number of lines of code in a given package/component.
+
+Further details on each smell are provided in the subsections below.
+
+## Unstable Dependency
+This smell represents a component (by *components* we refer to both classes and packages, but in the case of UD, we only mean packages/folders.} that depends upon a significant number of components that are less stable than itself.
+The stability of a component is measured using Martin's [instability metric](https://en.wikipedia.org/wiki/Software_package_metrics), which measures the degree to which a component (e.g. a package) is susceptible to change based on the classes it depends upon and on the classes depending on it.
+The smell thus arises when a component has a significant number of components -- the tool Arcan uses a 30% threshold -- it depends upon with an instability value higher than its own.
+A UD smell is detectable on Java package-like (or folders for C/C++ systems) elements only. A simplified example of UD is shown in Figure \ref{fig:unstable-dep}. 
+
+The main problem caused by UD is that the probability to change the main component grows higher as the number of unstable components it depends upon grows accordingly. This increases the likelihood that the components that depend upon it (not shown in Figure \ref{fig:unstable-dep} for simplicity) change as well when it is changed (ripple effect), thus inflating future maintenance efforts.
+
+\subsubsection{Hublike dependency (HL)}\label{sec:arch-smells-hl}
+This smell represents a component where the number of ingoing and outgoing dependencies is higher than the median in the system and the absolute difference between these ingoing and outgoing dependencies is less than a quarter of the total number of dependencies of the component \cite{Fontana2016}. A hublike dependency can be detected both at the package and at the class level.
+
+The implications of this smell for development activities are once again concerning the probability of change and the ease of maintenance. Consider, for example, the case represented in Figure \ref{fig:hublike-dep}.
+Making a change to any of the components that A depends upon may be very hard \cite{martin1994}, even though there is only one component depending on them.
+Additionally, the central component is also overloaded with responsibility and has a high coupling.
+This structure is thus not desirable, as it increases the potential effort necessary to make changes to all of the elements involved in the smell.
 
 # Architectural smell characteristics