Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Architecture.md (2021)

matklad.github.io

Post reply on HN
Print view View original

31–40 of 54 posts

Re: Architecture.md (2021)

#31

Post by evnix »

8organicbits wrote: post #13

This 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/

We have those pointless documents used by architects at my place of work, most of them have something on the lines of,

Micro services, Kafka, Kubernetes, because what if we have a billion users compared to the current 4k users.

GraphDB, what if SQL would not be enough

ElasticSearch, what if we have to do full text search along with stats.

But most of these documents are just short for any of these, "I want to try this new architecture/technology because it's fun, my colleague at a FAANG uses it, I've read the BOOK, and it looks good on my CV".

When they jump to design the next Big project, we have to deal with their decision, having twice as many services than our team, having to keep all the above mentioned DBs and technologies in sync which is of course a simpler problem than making those "big architecture decisions".

Sorry for the rant :(

Re: Architecture.md (2021)

#32

Post by kqr »

This sounds like it's suggesting adding documentation of the major units, what their purposes are, as well as their interfaces.

I agree with this. A map of the code is great. It's like an exploded-view drawing of a mechanical component. It helps highlight what goes where and connects how to what.

...but is this what "architecture" means? I was under the impression that architecture went beyond major-units-and-their-interfaces and had more to do with the decisions and assumptions that lead to those specific units and interfaces -- the why behind the what.

In other words, the "architecture", in my view, is the thing we might go against when we refactor things. Not because names and interfaces change, but because the rationale for having things a certain way might still apply only we don't know about it because those assumptions and decisions -- the architecture -- is rarely documented and still would not be under this proposal.

Re: Architecture.md (2021)

#33

Post by yawgmoth »

hbcondo714 wrote: post #5

> If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document I like this idea but IMHO, regardless of repo size, architecture can still has some place in a Readme. For example, I purposely placed a Mermaid sequence diagram[1] in the main Readme because I think it's important that all readers see and understand its workflow[2] [1] https://mer…

A natural language mermaid diagram builder would be really neat. Something to go think about...

Re: Architecture.md (2021)

#34

Post by hotelcoder »

evnix wrote: post #31
8organicbits wrote: post #13

This 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/

We have those pointless documents used by architects at my place of work, most of them have something on the lines of, Micro services, Kafka, Kubernetes, because what if we have a billion users compared to the current 4k users. GraphDB, what if SQL would not be enough ElasticSearch, what if we have to do full text search along with stats. But most of these documents are just short for any of these, "I want to try thi…

Uh, sounds like these documents are the opposite of pointless, and are in fact working exactly as intended.

Re: Architecture.md (2021)

#35

Post by bigfudge »

yawgmoth wrote: post #33
hbcondo714 wrote: post #5

> If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document I like this idea but IMHO, regardless of repo size, architecture can still has some place in a Readme. For example, I purposely placed a Mermaid sequence diagram[1] in the main Readme because I think it's important that all readers see and understand its workflow[2] [1] https://mer…

A natural language mermaid diagram builder would be really neat. Something to go think about...

ChatGPT had a good stab at it out of the box. It often only takes minor editing (just ask it to return mermaid)

Re: Architecture.md (2021)

#36

Post by esperent »

xavdid wrote: post #18

I've always found this to be a very useful practice. Many projects have a few core files (or packages / modules / whatever) where most of the changes happen. Being able to familiarize new contributors (or old returning ones) with those quickly really helps the startup time on a project. I've added architecture files to projects at multiple jobs now [0], [1] and they've been well received. They're not perfect, but the…

> Many projects have a few core files (or packages / modules / whatever) where most of the changes happen

Is there any way to view this automatically on GitHub? E.g. some kind of file change heatmap.

Re: Architecture.md (2021)

#37

Post by rzzzt »

marttilaine wrote: post #27

I 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

A README.md in each package/module/top-level directory is also rendered by GitHub's UI in the file list at the bottom (in locations like this: https://github.com/shipmight/shipmight/tree/master/src/backe...), I've seen this in some projects as well.

Re: Architecture.md (2021)

#38

Post by rzzzt »

karmakaze wrote: post #12
abid786 wrote: post #10

Earlier quoted context omitted.

What would that practically look like? How would circular dependencies be resolved, for example?

The two usual ways I've seen it is either by following the code/control-flow (calls or inverted as called by) or by following the data flow. You can select any code function and see the call (or called) graph (shown as a tree) , similarly for any data element and see the data elements that use (or is used by) graph and pruning cycles.

Call hierarchy trees usually cut cycles with a "there is already a node for this method elsewhere in the tree" end stop.

Re: Architecture.md (2021)

#39

Post by yawgmoth »

bigfudge wrote: post #35
yawgmoth wrote: post #33

Earlier quoted context omitted.

A natural language mermaid diagram builder would be really neat. Something to go think about...

ChatGPT had a good stab at it out of the box. It often only takes minor editing (just ask it to return mermaid)

It's wrong enough where writing raw mermaid is still faster at this time, IME.
Post reply on HN