Random thought: Every IDE I've used gives me the folder structure of the project on the left as a standard directory tree. Does any support navigating a project as a graph of dependencies?
Maybe you want a multitree.
Architecture.md (2021)
21–30 of 54 posts
Re: Architecture.md (2021)
#22One particular aspect of project architecture I often see people do wrong: a failure to have clear dependency structure between directories (and, often, too much stuff within a directory). This is particularly common if there is a directory named something like "common", "util", or "misc" (I am not actually arguing against having such directories, only noting they are prone to confusion). I developed the following ru…
Very interesting approach, thanks for taking the time to write it! I'll be evaluating my own projects with these guidelines- I think I've structured some of them like this without thinking about WHY
Re: Architecture.md (2021)
#23This approach sounds great as a low-maintenance model for open-source projects with many ad hoc contributors. For projects with dedicated engineers, consider ADRs instead. These require more maintenance, but capture the "why" and "alternatives considered", which can be immensely helpful when rearchitecting. See https://adr.github.io/
I don’t think “instead” is the correct word here. “As well” I think fits better.
ARCHITECTURE.md will have the current state of the architecture. ADRs is the log of decisions that got you there. Both are very useful.
Re: Architecture.md (2021)
#24A DEVELOPMENT or HACKING document should be enough for contributors, to cite the coding guidelines. When someone wants to contribute without understanding the code workflow, he should not contribute.
Re: Architecture.md (2021)
#25I think that's just more documentation to read which becomes outdated (read: lies) at the point in time someone moves code around with refactoring tooling in their IDE.
What about aspiring to "screaming architecture" instead? Don't hide your application domain in a "crates" directory. Do it the other way around.
Re: Architecture.md (2021)
#26> One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code. Here here! This sounds like such awesome advice. I wish we had bett…
I'd like to see something like [dep-tree]( https://github.com/gabotechs/dep-tree ) 's visualization augmented with a keyword or LLM vector search. Your query would highlight relevant files and clusters.
That's pretty much what https://sourcegraph.com/ are selling, is it not? (granted, they don't visualize their graph quite so graphically)
Re: Architecture.md (2021)
#27I experimented with something similar in one of my larger side projects a couple of years ago:
https://github.com/shipmight/shipmight/blob/master/src/ARCHI...
At the top of each file there was a tree of links to other ARCHITECTURE.md-files in the repo, like this:
* ARCHITECTURE.md Re: Architecture.md (2021)
#28A DEVELOPMENT or HACKING document should be enough for contributors, to cite the coding guidelines. When someone wants to contribute without understanding the code workflow, he should not contribute.
> When someone wants to contribute without understanding the code workflow, he should not contribute.
There are definitely many projects where you don't need to understand every single aspect of the codebase to be able to contribute a meaningful fix or even a feature.
It benefits the contributor and the project if they have a simple pointer to e.g. where the application logic code is, or where the distribution-related code is, etc.
Re: Architecture.md (2021)
#29I try to write docs like this. (Not markdown files, heaven forfend, and definitely not a random file in the root, of course, but these are quibbles.)
A problem, though, is that many things lack an architecture; they were grown and are a mess, and the procedural knowledge can't be put to a document without just pointlessly recapitulating the code itself in what is possibly a more confusing form.
Re: Architecture.md (2021)
#30Random thought: Every IDE I've used gives me the folder structure of the project on the left as a standard directory tree. Does any support navigating a project as a graph of dependencies?
Maybe you want a multitree.
See for example https://adrenaline.ucsd.edu/kirsh/Articles/In_Process/MultiT...