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

Architecture.md

matklad.github.io

Post reply on HN
Print view View original

91–100 of 159 posts

Re: Architecture.md

#91

Post by jlg23 »

baby wrote: post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "README.md"s should, IMHO, be in the module/package documentation in the source.

One can still link to those from the global README.md

Re: Architecture.md

#92

Post by exabrial »

kenniskrag wrote: post #20
exabrial wrote: post #17

So one thing we've done is write all of our applications the exact same way with well defined terms (on a wiki) and a commitment to no more than 4 layers. * Initiators (things that receive, decode, and validate input) * Controllers (Business logic containers. One function refers to one business action) * Services (Used by controllers to effectuate commands. Services absolutely cannot call other services) * Cross Cutt…

Why shouldn't a service call other services? One Service may extend the features e.g. network < encryption < http.

Three reasons:

First: we found that it creates a spider web of dependencies if we din't have this rule. Instead, if you return control to the controller after performing a discrete action, it makes sure that business logic stays out of services and keeps service functions short and directed.

Second: it makes it easy to keep the entire design in your head.

Third: It promotes composition. This leads to easier testability with mocks rather than having to resort to full blown integration tests for even the smallest things. (We still do integration tests, but mock tests can be churned out in volume and are less fragile).

Re: Architecture.md

#93

Post by exabrial »

Ma8ee wrote: post #48
kenniskrag wrote: post #20

Earlier quoted context omitted.

Why shouldn't a service call other services? One Service may extend the features e.g. network < encryption < http.

I don’t think the comment implies that a service can’t be layered.

Yes. So something like a "DatabaseService" might have a database connection, which is code we don't own. But the code we do own stops at that layer. This prevents a spider web of dependencies opening up.

Re: Architecture.md

#94

Post by macintux »

systemvoltage wrote: post #72
xyzzy_plugh wrote: post #65

Earlier quoted context omitted.

> Like how the fuck am I supposed to understand anything in there? By reading all the code? This is one of the superpowers of Go: for most Go projects, this is exactly what I'd do. Just read the code. It's easy to follow, it's all formatted the same, very little implicit behavior, and I don't need an IDE to do it. Few languages were designed to be read by others. Thankfully Go is one of them.

I am afraid, this doesn't quite cut the mustard. Code just can't replace a human readable Architecture diagram + explanations of whys of choices and hows of the system. Programming language doesn't replace this no matter how clear and modular it is. While Go is nice, you're vastly under-appreciating architectural documentation.

My standard argument regarding the criticality of documentation: no amount of code can ever explain what isn't there.

What optimizations have you tried that failed? What 3rd party tool used to be integrated but now isn’t because the maintenance burden was too high? Why is it safe to ignore this exception?

Re: Architecture.md

#95

Post by Switch1983 »

That's good advice, even just an architectural diagram with notes on each component. It isn't just for public projects though, all projects have new developers coming in from time to time and the easier it is to present the project in a clear way, the less time you'll end up having to spend onboarding someone.

.....although I can be as sloppy as the next person at keeping documentation up to date which is why I think even a high level design and notes is better than nothing.

Re: Architecture.md

#96

Post by 8bitsrule »

I've gotten used to put 'beginning of ...' and 'end of ...' comments into a large project to demarcate large functions or collections of them, along with inline documentation. Line numbers are worthless for this.

It'd be great if there were FORMAL ways * to demarcate that are standard (yeah, what XKCD said) in ALL languages. Then anyone could just run a 'show architecture' application on the code and it would always be current.

After a few months (or thousands of loc), that map in your head starts to fade.

* EDIT: call it, say, CAML

Re: Architecture.md

#97

Post by austincheney »

My approach:

1. put a one line comment at the top of each code file.

2. The build extracts that comment and dynamically updates a readme.md for the directory that describes each code file.

3. The build also produces a master document that includes the same summaries in a single document.

This provides a light indication of what each code file is and how they are organized into directories. It doesn’t provide any indication of flow control or any kind of logical linking.

Since the documentation is prepared via automation you can add new files or delete files and the documentation remains current. If such a comment is missing from a code file the build fails with error messaging. Keeping each comment up to date is still manual though.

Re: Architecture.md

#98

Post by pronoiac »

harikb wrote: post #6

Any word on supporting diagrams inside GitHub flavored markdown?

The method I've considered: add a separate .mermaid file, render it as a png or svg file, and put that in the markdown file.

Re: Architecture.md

#99

Post by danaliv »

Aeolun wrote: post #89
utborin wrote: post #29

As someone who is in week two of spooling up on a multi-million-line codebase where most of the original authors have moved on to other projects, please, I beg you to heed this advice. I spend the vast majority of my time figuring out where a change needs to happen. The patches themselves are no more than 10% of the work. (The other significant factor is running tests.)

Well, at least it sounds like you have tests :)

Good point. :)

Re: Architecture.md

#100

Post by iamlolz »

Is there something similar for creating an overview of an entire web application to plan and communicate feature set, server stack, application structure, scheduled jobs, etc?
Post reply on HN