Feb 10, 2021 07:00:00

The 'architecture documentation' of a program should be tedious, so how should it be written?

When you newly join a development project, understanding the project is the first priority. However, there are times when you don't have the documentation to get the big picture and you have no choice but to grab fragmentary information from your code. Engineer

Aleksey Kladov points out that for large projects it is better to include 'ARCHITECTURE.md' which indicates the 'architecture of the entire project' so that new developers can understand the project smoothly. ..

ARCHITECTURE.md
https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html

While involved in the development of open source projects, Mr. Kladov noticed that 'the amount of knowledge about the project architecture' makes a big difference in development speed. For developers who have no knowledge of architecture, a large amount of code is the same as 'disjoint data' and takes time to read. But with knowledge of the architecture that shows 'where and what,' Kladov points out that code is no longer disjointed data.

It's hard work for new developers to understand the architecture by relying solely on code. A 'README.md' that outlines the project and a 'CONTRIBUTING.md' file that shows the development policy are often attached, but they are not information of a nature that helps the understanding of the entire project. Against this background, Kladov emphasizes the importance of having an architecture-indicating 'ARCHITECTURE.md', especially for large projects with more than 10,000 lines of code.

At the heart of ARCHITECTURE.md is a '

code map ' that shows the 'big picture of the project' and the connections between the codes. Kladov says the codemap should only describe what each code does, where it is, and how it interacts, with detailed explanations in a separate document. I'm pointing out.

Kladov also commented, 'The content of ARCHITECTURE.md should be unaffected by code changes.' The emphasis is on low maintenance costs that can be reviewed every few years, and specific methods such as 'files and modules can be searched by name without creating links' are also shown. Kladov says it's also important to clarify other parts that are difficult to understand just by reading the code, such as 'parts that are immutable in the project' and 'layer and system boundaries'.

'Architecture.md' is actually prepared for '

rust-analyzer ', which Mr. Kladov is involved in development as a core member.

rust-analyzer / architecture.md at d7c99931d05e3723d878bea5dc26766791fa4e69 · rust-analyzer / rust-analyzer
https://github.com/rust-analyzer/rust-analyzer/blob/d7c99931d05e3723d878bea5dc26766791fa4e69/docs/dev/architecture.md

An image diagram showing the structure of the entire project as shown below ...

A code map is provided and devised to help developers who are new to the code understand.

In addition, Mr. Kladov himself tends to neglect the document creation, and commented that he is a person who can just 'simplify' the reason for modifying the program. It emphasizes that it is not an assertion that 'documentation is good in itself, so let's write more documentation', but that we just want you to understand the importance of describing the architecture.