Merge pull request #119 from BrenoFariasdaSilva/DOCS-README

Enhanced Documentation: Detailed Design Patterns and Architectural Overview.

README.md

@@ -131,6 +131,57 @@ See `NumberOfLogStatements.java` and the test examples (`NumberOfLogStatementsTe
 
 Note: CK separates classes, inner classes, and anonymous classes. LOC is the only metric that is not completely isolated from the others, e.g., if A has a declaration of an inner class B, then LOC(A) = LOC(class A) + LOC(inner class B).
 
+## Project Structure
+
+CK is a Java code metrics collection tool, streamlined into a simple structure that revolves around three primary packages:
+
+- **ck:** Contains the core classes that drive the metrics collection process.
+- **ck.metrics:** Hosts the metric definitions and implementations.
+- **ck.utils:** Utilities supporting the metrics collection process.
+
+For brevity, within this documentation, package prefixes such as `com.github.mauricioaniche.ck` are omitted.
+
+## Architecture
+
+### Core Components
+
+- **CK:** The backbone class of the tool, `CK` manages the orchestration of the entire metrics collection process. It initializes metric finders, handles file partitioning based on available memory, sets up AST parsers with appropriate environment settings, and manages execution flow across different directories and JAR dependencies. It dynamically adjusts its behavior based on user inputs like `useJars`, `maxAtOnce`, and `variablesAndFields` to optimize the processing of Java files for metrics collection.
+- **Runner:** The entry point of the application, housed in the `ck` package. This class processes command-line arguments to configure and launch the metrics collection process. It handles user input for the project path, JAR inclusion, file partitioning, metrics detailing, and output directory setup. `Runner` orchestrates the overall execution by initializing and utilizing the `CK` class and handling result output through `ResultWriter`.
+- **MetricsExecutor:** This class extends `FileASTRequestor`, a component of the Eclipse JDT (Java Development Tools) core. It plays a pivotal role in the CK framework by orchestrating the metrics collection process. The `MetricsExecutor` coordinates the creation of the Abstract Syntax Tree (AST) for Java source files, which is essential for analyzing and extracting code metrics.
+
+### Metrics Identification
+
+- **MetricsFinder:** This utility class, located in `ck.utils`, plays a crucial role in the dynamic identification and instantiation of metric collector classes within the CK framework. It targets classes that implement the `ClassLevelMetric` and `MethodLevelMetric` interfaces from the `metrics` package.
+
+  The `MetricsFinder` utilizes the `Reflections` library to scan and load metric collector classes at runtime, which enables the CK system to be extensible and adaptable to new metrics without requiring modifications to the core architecture. This feature is particularly useful for integrating custom metrics into the analysis process seamlessly.
+
+### Metrics Collection
+
+- **CKVisitor:** An integral component of the CK framework, `CKVisitor` extends the `ASTVisitor` class provided by the Eclipse JDT (Java Development Tools) library, enabling detailed analysis and metric collection directly from Java source code's Abstract Syntax Tree (AST).
+
+  The visitor is designed to traverse various nodes of the AST, such as types and methods, and apply specific actions at each node. It effectively manages a stack-based hierarchy of classes and methods, allowing metrics to be calculated and collected in the context of the current node's scope.
+
+- **CKASTVisitor:** Implemented by metric classes in `ck.metrics`, allowing each metric to handle specific AST nodes of interest, such as method invocations and class instance creations.
+- **ClassLevelMetric** and **MethodLevelMetric:** Interfaces defining methods for collecting class-level and method-level metrics, respectively.
+
+### Results Notification and Storage
+
+- **MetricsExecutor:** After collecting metrics, it uses a Notifier design pattern to broadcast the results using the `CKNotifier` interface.
+- **Anonymous class in Runner.main:** Fills the `CKClassResult` and `CKMethodResult` with the collected data.
+- **ResultWriter:** Utilizes the collected data to generate and store results in .CSV format.
+
+## Design Patterns
+
+CK framework incorporates a number of well-established design patterns to enhance modularity, extendibility, and maintainability of its codebase. These patterns enable the framework to efficiently handle complex operations such as traversing abstract syntax trees (AST), collecting metrics, and notifying results. Below are the key design patterns utilized:
+
+- **Visitor Pattern:** The `CKVisitor` and `CKASTVisitor` interfaces implement the Visitor pattern, which is pivotal in handling operations on various AST nodes without altering the classes of the elements on which it operates. This pattern is especially beneficial in scenarios where a component needs to perform distinct and unrelated operations across a class hierarchy of AST nodes. It simplifies code by externalizing operational logic into visitor objects, facilitating easy addition of new operations without modifying existing node classes. This separation of concerns leads to a more maintainable and extensible codebase, where AST node structures and operations on them are decoupled.
+
+- **Notifier Pattern:** CK adopts the Notifier pattern through the use of `CKNotifier`, which acts as a central mechanism to broadcast the results of the metrics collection to all registered observers. This pattern is crucial for creating a loosely coupled architecture where the subject (metric computation process) is independent of its observers (results processors or report generators). This enables CK to notify multiple components about the completion of metric calculations without coupling to specific components, which enhances flexibility and scalability of the system.
+
+- **Factory Pattern:** The instantiation of metric collectors is managed by `MetricsFinder`, which embodies the Factory pattern. This pattern is utilized to encapsulate the logic of instantiating specific metric collector classes based on runtime decisions. The Factory pattern simplifies the process of adding new types of metric collectors without disturbing the existing code, providing a plug-and-play architecture where new metrics can be introduced seamlessly. It also aids in maintaining separation of concerns, as the process of creating metric objects is isolated from the core logic of metric collection.
+
+By leveraging these design patterns, CK efficiently manages complexity and ensures that the framework remains robust, adaptable, and easy to extend as new requirements and metric types emerge.
+
 ## How to use the standalone version
 
 You need at least Java 8 to be able to compile and run this tool.