skodapetr/linked-code

Connecting software artifacts.

Linked code

A common practice in software development is to see diagrams and code as a plan and a realization/implementation. In the worst-case scenario, diagrams are images accompanied by text that the developers need to study and implement them. Such scenarios are not uncommon. The diagrams and text together form a specification, an artefact created by an analyst. Yet those artifacts are often not owned by the developers, although they may be tasked to keep them up to date. Approaches, such as diagrams as code, aim to narrow the gap between the code and the specification. Generating code from specification also help.

Yet inevitably, the code and the specification start to diverge. The main reason is that there can be only one source of truth. The source of truth is the code, the ultimate definition of architecture, data model and behaviour. The main drawback of the code is that it is way too detailed. As a result, it is hard to reason about software using only the code. We need abstraction; we need the diagrams.

Many tools focus on a top-down approach where code is the product of specification. Such tools are excellent for use-case analysis, data modelling or software design. Yet once we start with the implementation, the code quickly becomes the main defining artefact. We need to transition some of the information and responsibilities from the specification to the code.

For example, a class model may define a data model for an application, until there is code with a domain model implemented in a programming language of choice. Once implemented, the code always specifies the domain model, not the class diagram.

The idea behind this repository is to embrace this transition and allow developers to connect (link) their code to the specification. The specification can be created and modified based on the existing code and vice versa. A developer should not need to search documentation in order to implement a class that will temporarily hold business data. On the other hand, an analyst, or an architect, should be able to quickly identify parts of the software that are using given business data.

Data Models

The application is build around several data models.

Annotations

Instances are extracted from source documents. They capture low level information like start of an entity definition, name, etc..

Instance

Annotations can be aggregated into instances. Instances represent entities and their properties in individual files. If the same entity is declared in multiple class it is represented as multiple instances of same entity.

As this model is quite simple it should be used as the main model to share information.

Aggregation

Build on instances this model provides aggregated view. Information from multiple instances are merged together to provide unified view of the data. Provenance information to level of instances is preserved. As a result this model should be used only for analytical purpose.

linked-code's Issues

Add suport for resources

For example we may need to connect enums or constants:

CONTEXT_OPEN = "open"

CONTEXT_CLOSE = "close"

NEXT_KEY = "key"

VALUE = "value"

LinkML

https://linkml.io/

Update input and output handling

Each executable script should be able to

• load input from a file
• load input from a stdin
• write output to a file
• write output to a stdout
• autodetect input format
• let user select output format

VS Code : Better comments plugin

https://github.com/aaron-bond/better-comments