Where I’ve seen this done well, it has always been rolled into CONTRIBUTING as a lightweight place to point new developers toward any non-obvious logical entry points, rather than as a place to bother with articulating high-level architectural decisions.
That is to say, it firmly sticks to the “what” instead of the “why” and makes no pretense of being a comprehensive document. As you point out, the “why” is probably out of date, but “why” also doesn’t really matter to anyone who hasn’t already wrapped their brain around the whole mental model of the application.
No ready examples immediately jump to my mind, but I know I recently saw a good page in a go project noting the rough equivalent of a main() that was neither the primary entry point of the application itself nor a cleanly separated area of concern (i.e. module). One could argue this already suggests a poorly designed architecture, so I wish I had this example ready at hand - this is where I’d make some kind of argument about not letting “perfect” get in the way of “practical”, but of course I see the silliness of that point when I’m already speaking at a purely theoretical level.
The architechture.md file mentioned is quite long imo. I wonder whether documenting the code like a library would work (easier in some languages than others), and providing a list of entry points/interactions in a short architechture.md (I often struggle with finding where the work actually starts). In-source docs have much less chance of going stale.
Also, for those not bothered to check what exa -TD does, it prints a tree of the directories at .. Funny the author didn’t just say tree
The architechture.md file mentioned is quite long imo.
Mea culpa :) In my defense, rust-analyzer is a deep and complex project which sits closer to the 200k limit, so there’s a lot of ground to cover. And yes, pointing out entry points explicitly is a good idea, I’ve added separate section for them, thank you!
I don’t think that in-source docs are a substitute for architecture.md though. They are good for explaining what are you looking at, but bad at helping to find where to look in the first place. In my experience, the central document is also, counter-intuitively, easier to keep up to date. I still forget to update the docs even if they are next to code, but with a single document I at least have a workflow to check if the docs are up to date. Finally, with inline docs you probably want to get an “atlas of fine grained maps” rather than a “coarse grained map”. An interesting idea to bridge the tho approaches is to auto-generate codemap out of specially-marked doc comments.
That being said, rust-analyzer also enforces “each module has a docstring” property, and you write about providing a list of entry points to find where the work actually starts, so I expect that we are more in agreement than not :)
In my Dinit project, it’s called DESIGN. It’s pretty brief and only succintly covers a few things, but importantly points where to look in the source for various things; then there are large chunks of comments within various sources files which give the details relevant to that particular source. The DESIGN file also spells out the design considerations and philosophy, and gives very high-level information as to how the software is put together.
It’s really hard to build up a picture of a how a project is put together. An overview like this can save hours of having to slowly piece it together by trawling source more-or-less at random. But, a lot of information can still live in the form of comments within the source code. (Of course, they need to exist, and to be kept up to date).
Interesting concept, but the software itself hasn’t moved in a while. The author started a rewrite in python according to this: https://github.com/vitiral/artifact/issues/271 – but neither repos have had updates in about half a year.
Artifact-rs itself works just fine, though, so perhaps it can be thought to be finished instead of dead.
You see a feature that could be worth implementing in a project, the feature is probably 50loc, but you have to spend hours reading the code to see where it would be best integrated…
If you’re lucky, a maintainer can walk you through the important parts of the project and give you hints about which part of the code you’ll need to touch.
Documenting the architecture / big picture is obviously a good idea. It is an old good practice.
I am just not sure whether a separate file is a best way. I rather recommend doing the documentation as a comprehensive book where Architecture is one of the chapters. From single source you can generate various formats (PDF, XHTML, man pages, help files, eBooks etc.)
If you don’t have the time to write this kind of document, at least write something along the lines of: “In order to understand this project, start with reading the source code file(s): [short list of source code files]”
Also a historical list of high level decisions with dates is way more helpful then many imagine.
In my day it was called
HACKINGand it documented the code as it stood two years ago, if you were lucky.Where I’ve seen this done well, it has always been rolled into
CONTRIBUTINGas a lightweight place to point new developers toward any non-obvious logical entry points, rather than as a place to bother with articulating high-level architectural decisions.That is to say, it firmly sticks to the “what” instead of the “why” and makes no pretense of being a comprehensive document. As you point out, the “why” is probably out of date, but “why” also doesn’t really matter to anyone who hasn’t already wrapped their brain around the whole mental model of the application.
No ready examples immediately jump to my mind, but I know I recently saw a good page in a go project noting the rough equivalent of a
main()that was neither the primary entry point of the application itself nor a cleanly separated area of concern (i.e. module). One could argue this already suggests a poorly designed architecture, so I wish I had this example ready at hand - this is where I’d make some kind of argument about not letting “perfect” get in the way of “practical”, but of course I see the silliness of that point when I’m already speaking at a purely theoretical level.A related good idea is Architecture Decision Records to explain and justify how the architecture evolved over time.
The architechture.md file mentioned is quite long imo. I wonder whether documenting the code like a library would work (easier in some languages than others), and providing a list of entry points/interactions in a short architechture.md (I often struggle with finding where the work actually starts). In-source docs have much less chance of going stale.
Also, for those not bothered to check what
exa -TDdoes, it prints a tree of the directories at.. Funny the author didn’t just saytreeMea culpa :) In my defense, rust-analyzer is a deep and complex project which sits closer to the 200k limit, so there’s a lot of ground to cover. And yes, pointing out entry points explicitly is a good idea, I’ve added separate section for them, thank you!
I don’t think that in-source docs are a substitute for architecture.md though. They are good for explaining what are you looking at, but bad at helping to find where to look in the first place. In my experience, the central document is also, counter-intuitively, easier to keep up to date. I still forget to update the docs even if they are next to code, but with a single document I at least have a workflow to check if the docs are up to date. Finally, with inline docs you probably want to get an “atlas of fine grained maps” rather than a “coarse grained map”. An interesting idea to bridge the tho approaches is to auto-generate codemap out of specially-marked doc comments.
That being said, rust-analyzer also enforces “each module has a docstring” property, and you write about providing a list of entry points to find where the work actually starts, so I expect that we are more in agreement than not :)
I agree with this!
In my Dinit project, it’s called DESIGN. It’s pretty brief and only succintly covers a few things, but importantly points where to look in the source for various things; then there are large chunks of comments within various sources files which give the details relevant to that particular source. The DESIGN file also spells out the design considerations and philosophy, and gives very high-level information as to how the software is put together.
It’s really hard to build up a picture of a how a project is put together. An overview like this can save hours of having to slowly piece it together by trawling source more-or-less at random. But, a lot of information can still live in the form of comments within the source code. (Of course, they need to exist, and to be kept up to date).
artifact is an interesting tool for doing this throughout the codebase in the hopes that it stays more up to date and easily traversable.
Interesting concept, but the software itself hasn’t moved in a while. The author started a rewrite in python according to this: https://github.com/vitiral/artifact/issues/271 – but neither repos have had updates in about half a year.
Artifact-rs itself works just fine, though, so perhaps it can be thought to be finished instead of dead.
Needing this happens all the time!
You see a feature that could be worth implementing in a project, the feature is probably 50loc, but you have to spend hours reading the code to see where it would be best integrated…
If you’re lucky, a maintainer can walk you through the important parts of the project and give you hints about which part of the code you’ll need to touch.
Documenting the architecture / big picture is obviously a good idea. It is an old good practice.
I am just not sure whether a separate file is a best way. I rather recommend doing the documentation as a comprehensive book where Architecture is one of the chapters. From single source you can generate various formats (PDF, XHTML, man pages, help files, eBooks etc.)
THIS!
If you don’t have the time to write this kind of document, at least write something along the lines of: “In order to understand this project, start with reading the source code file(s): [short list of source code files]”
Also a historical list of high level decisions with dates is way more helpful then many imagine.