how to achieve two-way binding of document and code

Document isomorphism is a technical concept of keeping code consistent with documentation. 
It can read formatted documentation and automatically add documentation to code, such as 
in the form of comments or only in the IDE; at the same time, it can also Will read the 
documentation in the code, automatically update the documentation, or perform tests and
diffs on the documentation.

Introduction 1: Pain points of documentation and annotations

Recently, while designing the architectural description language Forming, I am writing a new book around this conceptual system. During the period, I read a series of architecture books, such as the concept of a “refined document” in the Highlighted Core section of “Domain-Driven Design”.

Refined documentation is to write a very short document 
(3 to 7 pages, not too much content per page)
that describes the main interactions between the 
core domain and the core elements.

The pain of writing documentation, I think most programmers understand, its pain is mainly reflected in two aspects: I don’t want the documentation, I don’t have it when I want to read the documentation. As the book says, the common risks of independent documents are mainly in two aspects:

1. Documentation may not be maintained
2. Documentation may not be read by anyone
3. Documentation may fall short of simplifying complexity due to multiple sources of information

Likewise, for comments in code, the problem is similar, so to speak: comments are documentation. Moreover, another common problem is that there may be documents, comments, and code in the project. The inconsistency of the three is a more serious problem.

Therefore, in this article, we will explore document isomorphism, that is, how to automate the synchronization of annotations and documents. In fact, what I’ve been thinking about is the comment-code-document consistency check, maybe I’ll discuss it in the next article, combined with Design by Contract.

Introduction 2: Forward Generation and Feedback Design

At design time, with architectural design tools such as Forming or UML, what we do is a forward generation, such as generating the relevant code directly through UML. From the process, it is generally:

1. Write and design DSLs. Design a DSL (Domain Specific Language) that describes the domain.
2. Write code. Write a DSL description system provided by programming tools.
3. The tool generates code. That is, the tool parses the relevant DSL and generates code on the target system.

When evolving, such as when using architecture guarding tools like ArchGuard or Guarding, what we do is reverse engineer, that is, analyze the code and compare it to the original design of the system. From the process, it is generally:

1. Automated analysis. Find the right tools to automate the analysis of code written by developers.
2. Design comparison. Compare the analyzed data structure with the data structure generated by the DSL.

For documentation, it should be the same, so we can design a documentation tool to automatically generate annotations and identify annotations in the system to compare with the original document.

document isomorphism

Based on the above two basic ideas, we can define the concept of document isomorphism:

Document isomorphism is a technical concept of keeping code consistent with
documentation. It can read formatted documentation and automatically add 
documentation to code, such as in the form of comments or only in the IDE; 
at the same time, it can also Will read the documentation in the code,
automatically update the documentation, or perform tests and diffs on 
the documentation.

When I first conceived it, I just wanted to use this concept to automate the synchronization of comments and code, but as I learned more about the related content, I found that this is a very useful thing, and I will follow up on The relevant introduction is carried out on the mode.

As I designed the Forming implementation, I tried to summarize some points:

1. Highlight the core. That is, distinguish the core domain from the general domain, and put important energy into the design of the core part of the system.
2. The code is two-way bound to the document. That is the forward generation and feedback design mentioned in the previous section.
3. Document coding. That is to design a domain-specific language to describe the description and realize the isomorphism with the code through a structured form.

Highlighting the core: distinguishing the core domain from the general domain

In a system, it is bound to be filled with a large number of domain-related concepts, and we cannot discuss each concept. So, when designing, we distill out the core parts of the system as described in the book Domain-Driven Design. Combined with our unified language-related design, we will take vocabulary-related concepts. So, in this part of the design, it consists of two parts:

1. Concept Glossary. It can be maintained based on simple expressions, such as lists in Markdown, or in CSV format.
2. Refine documentation. Conceptually, I prefer to use a DSL to design. But in YAML or CSV form, it’s simpler to parse and maintain.

From the two parts of the document, the mapping of the system code and the document is formed.

Code and document two-way binding

For document isomorphism tools, the difficulty is still:

1. Parsing of programming languages. That is, the customs data model of the generated code, records the relevant information such as the number of lines, files, and locations of key concepts, so as to facilitate automatic modification.
2. Display and update mechanism for code and documentation. That is, whether we display the document, whether the document needs to be corrected, etc.

In terms of implementation, the existing technologies are relatively mature.

Document Coding: Domain-Specific Language Design

Finally, to review my definition of document coding:

Document coding, writing the document in a domain-specific language like code 
and managing it by referring to the way of software development 
(such as source code management and deployment). It can
be edited, previewed, viewed with the help of specific tools, or deployed to 
the server through a dedicated system. A common architectural pattern for document
coding for non-technical people is Edit-Release-Development Separation ”

Document Isomorphic Pattern

In the past period of time, when thinking about this design, I was thinking about how documentation and code get along, and I also summarized some patterns by the way.

Document Isomorphic Document Pattern: Document Testing

Rust's philosophy on documentation is not to write documentation alone. First, 
the code itself is the documentation, and second, the comments of the code are
the documentation. Rust can not onlyautomatically extract the documentation in
the code to form a standard form of documentation collection,
but also test the sample code in the documentation.

Last year, the main reason I thought about documentation code was seeing documentation testing in Rust: rustdoc support for executing documentation examples, as tests, to ensure documentation is up-to-date and valid.

Well, the pattern we have made is to do some upgrades on the basis of this, that is, to synchronize the business concept document into the code.

Document Isomorphic Pattern: Executable Documents

An executable document is a document that can be compiled and run directly. This is rustdoc after, I try to write the Exemd project. Can automate some code in Markdown files, support: Rust, Ruby, JavaScript, TypeScript, and other languages, and support the form of dependencies, that is //, the colordependencies of Rust can be introduced through.

// exemd-deps: colored;version=1.8.0

extern crate colored;




use colored::*;




fn main() {

println!("{} {} !", "it".green(), "works".blue().bold());

}

And this mode is a document-based model. In my original design, it can also directly import executable source code. It works for me in the mode of writing articles and writing books.

Document Isomorphic Pattern: Code Comment Separation

Code comment separation, that is, we don’t need to write comments in the code. Comments are written in other places in the code, and they are written for people to see, such as the way to use subsequent IDE presentations.

Document Isomorphic Pattern: The IDE automatically renders comments

Under this mode, comments exist in the form of documentation, but are not written in the code and exist independently. We can use the IDE plugin way to load annotations.

Based on the concept of cloud IDE and the cloud R&D architecture model, it can solve the problem that documents do not exist in transmission.

other

Since I started researching ” cloud R&D “, I have been researching the coding of software development, from various types of automation to various types of coding, such as designing various domain-specific languages. Documentation is also an important part of it, and our purpose should be: comment-code-document automatic consistency.