
It is amazing anything works at all. A rant on software development - ssd532
https://twitter.com/Rich_Harris/status/923392376592392197
======
karlmcguire
This is the second "twitter blog post" I've seen in a week. And by that I mean
10+ consecutive tweets. Talk about bad UX.

~~~
ssd532
Is there a word for it? If not we will soon need it. There are many such long
tweet sequences I have seen, some by journalists. So it's becoming a common
thing like web logs -> blogs two decades ago.

~~~
gumby
I thought there was some site that took twitter streams like this and turned
them back into text. In the current scheme, where your eye can't simply flow
through the text, makes them unreadable and useless to me, so I no longer even
try.

------
sidlls
Not all software development is like this. In some sectors it's treated as a
proper engineering discipline. Circles where javascript, node and logging into
Twitter are a thing are where you find this casual indifference to
documentation, garbage interfaces, dozens of competing APIs and so forth. The
reason is straightforward: in these areas the problems are neither interesting
nor that hard, and so developers get bored and invent complexity where it need
not exist.

~~~
ssd532
I have seen the same incomplete and inconsistent documentation for many Google
and Microsoft projects including Kubernetes and many cloud based services. And
it is not only about their REST APIs but for their SDKs for programming
languages/frameworks not limited to Javascript/Node.

~~~
hobofan
Why would it be different for Google or Microsoft projects?

I think sidlls was talking about industries where lives are at stake, like
aviation , where things move slowely and follow a strict QA process. There you
have formally verified systems and the like, but you also have to make
tradeoffs like working with a limited subset of C because that is formally
verifiable.

~~~
ssd532
I completely agree on that part. I wanted to highlight that at least the
bigcos should provide consistent and comprehensive documentation for their
popular libraries/APIs.

------
giardini
"If builders built houses the way programmers built programs, the first
woodpecker to come along would destroy civilization."

\- Gerald Weinberg

~~~
chrisco255
Unlike houses, software has a very organic nature to it. Requirements are
constantly shifting.

~~~
EliRivers
It's certainly true that the best software I ever worked on didn't suffer
shifting requirements.

The customer literally never reported a single bug.

Every requirement was fully tested and fully traceable from requirements
document to the exact page of the design document that was going to meet it to
the exact lines of code that met it to the module level tests that tested that
code to the verification test that tested the requirement at a higher level.

The documentation was beautiful; a document that compiled into two other
documents, one being the source code and one being an interlaced design and
discussion document with source code in it - one could read this document,
read the design, see linked requirements documents, see linked test documents,
read the explanations and justifications, interspersed with the source code
that then implemented that design. Nobody wrote pure code; we wrote
interspersed design and discussion and code, which was then reviewed as a
whole.

Even though the project ran for a decade, a newcomer could fully understand
everything about the code from reading this document. Within a week, a
newcomer fully understood, and if they ever saw code they didn't understand,
this document would show them what it was trying to achieve, what requirements
it was supporting, how it was being tested. It was 100% waterfall, and
fantastically high quality. The customer, after suing one of their other
contracted suppliers for failure to deliver working software over a period of
years, then came to us to ask if we could make that software too. The high-
quality of the work meant that we actually spent less; once designs were
approved following review, they were very rarely revisited or changed. Once
code was written that met that design, it very rarely needed reworking. Large
pieces of the software were written once, correctly, and five years later were
still working, exactly as they had been written. When you know what you're
supposed to be making in advance, the level of quality you can reach and the
low cost of doing it can be astounding.

It all relied on a very high quality of customer without shifting
requirements. Sad but true; high quality customers are in very short supply.

I frequently find myself saying at my current workplace "If you don't know
what you're meant to be making, the odds of getting it right are very slim."
It seems incredible that I have to say it, but I do, and we frequently start
making things without a clear picture of what it's meant to be. Still, if
customers can't decide what they want, they pay the price.

------
caseymarquis
I like modern js for frontend work, but this is why I like statically typed
languages on the backend for anything critical or complicated. Even if the
documentation for a library is out of date or for a different version, IDE
autocompletion allows you to figure things out on your own. Not just when type
hints were provided, but in every case.

