Tools

JQassistant

How about you could scan your Java,C# code and create a graph representation describing all artifacts and their relations. You could then query about your own code metrics. This is what jqassistant.org is doing. It allows to create rules for projects in the format of Cypher queries. Cyper is the query language for the Neo4j backend.

The website lists below use cases:

  • Enforce naming conventions, e.g. EJBs, JPA entities, test classes, packages, Maven modules etc.
  • Validate dependencies between modules of your project
  • Separate API and implementation packages
  • Detect common problems like cyclic dependencies or tests without assertions

It provides pre-build concepts i.e. a java-ddd concept providing basic constraints for structure and architecture of a project applying domain driven design.

An example constrain verifying that a repository only returns Aggregates could look like this

=== Aggregate Rules

[[architecture:AggregateRepository]]
[source,cypher,role=constraint,requiresConcepts="java-ddd:Aggregate*,java-ddd:Repository*"]
.Only aggregates are allowed to be returned by repositories.
----
MATCH
  (repo:DDD:Repository)-[:DECLARES]->(:Method)-[:RETURNS]->(t:Type)
WHERE
  NOT t:DDD:AggregateRoot
RETURN
  repo.fqn as Repository, t.fqn as IllegalReturnType
----

It integrates very well with architectural decisions records where it can be used as fitness function. They cyper query would simply be added to the architectural decision record. Not only java classes but also maven dependencies, yml files and other project artifacts are indexed and can be part of such a fitness function.

Project Documentation

Arc42

arc42.org is an excellent project documentation template. It targets to make documentation painless by providing a comprehensive structure, limited to absolutely necessary parts. It also includes more recent concepts like architectural decisions records Overall it makes documentation lean.

It is available under the Creative-Commons Sharealike 4.0. license and continuously updated in all major formats (docx, markdown, asciidoc, …).

There are also plenty of examples available for real/hobby projects. I found biking.michael-simons.eu/docs/index.html to be a very good example.