Hacker News Reader

Comment by zzzzzzzza | Hacker News Reader

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.”

~ Fred Brooks, “The Mythical Man Month”

Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql), more expressive type systems e.g. rust, haskell, typescript perhaps (though I am not completely sold on typescript yet myself) nix/nixos (or more mainstream, hashicorp products/ansible/puppet/docker) kubernetes and co. (most people probably don't need)

View on HN

But my domain model is

    Store
    =====
    Id int
    Col1 varchar
    Col2 varchar
    Col3 varchar
    ...
    Col134 varchar
    foreignKey1 varchar
    foreignKey1Type varchar
    foreignKey2 varchar
    foreignKey2Type varchar
    ...
    foreignKey10 varchar
    foreignKey10Type varchar
    validFrom varchar
    validTo varchar
    isActive boolean
    deleted boolean

I don't need your flowcharts, I'll be heading for the door!

Ah, it’s good they used varchar, at least now you can store everything in those columns.

And there’s a multitude of ways to soft-delete too!

This is much better than some schemas I’ve seen.

Not 2 years ago, I saw an entire Joomla schema converted to Microsoft Excel tables which we should use to port the website. Our team just ignored the effort.

Probably the most important part of that effort was to keep the project managers and analysts busy fighting over that nonsense, providing aircover for the devs to actually do the work.

Good guess but this is third world country public school level. The friendly sextagenarian did his best but he was only comfortable with PHP and Excel.

Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.

This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.

The database was meant to be the CMS and SQL was designed to be human readable.

Counterpoint: If small design decisions require global SQL schema changes, it slows you down. And small barriers to change will, in aggregate, kill you.

Eg, over a month of iterations: "Can we add another field to user registration? It should be free text. Oh, they should select from a list. No wait, make it a date. Actually a date and a text field. No wait, dump the text field."

Sometimes slowing down these changes is a good thing. But often, being able to ship each iteration along the way will help your design team converge on the best solution. If you need to write a schema migration for every iteration, it kills the ability of your team to experiment and explore the space of "what should our product actually look like".

Faster iterations = more iterations = better product in the long term. Sometimes the best long term result requires some random stuff getting crammed into a big JSON field in your database in the short term.

Sounds like the real problem is that there's too much friction with schema migrations.

This is only a slight exaggeration of real things that exist in products like SharePoint or Visual Studio Team Services

That's scary to even read

> But my domain model is...

No it isn't. That's the model for the representation of the actual domain model. The actual domain model may well be "idk everything" (then you're SOL) or it just may not be formalized (then you might want to fix that).

Absolutely this! No matter what the system is, the important part is being able to laser down to any lower levels of abstraction and reason about the specifics there. Higher level abstraction docs are summaries or getting started guides at best.

Agreed as well, though there is also the case of communicating the high level flows to others that are not software experts so that everyone has a common understanding and doesn’t have to rely on a few key developers with the knowledge. Most smart folk who aren’t developers reason pretty well about architectures so you want them to be self sufficient too.

Also as a user! User documentation should imho explain what are the datastructures that a piece of software is manipulating, and what the dependencies between them are.

The rest of the UI, I can figure out by myself.

There are exceptions though, where the domain model is trivial, but you will be mystified without the sequence diagrams. Paxos for example has a trivial domain model (a value that's supposed to be kept identical on all nodes in a distributed system) but the consensus algorithm is non-trivial enough that a lot of people claim you should not even try to implement it (and opt for Raft)

Reply on news.ycombinator.com