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

The Opposite of Documentation is Superstition (2020)

buttondown.com

Post reply on HN
Print view View original

71–80 of 87 posts

Re: The Opposite of Documentation is Superstition (2020)

#71

Post by [deleted] »

dingnuts wrote: post #67
jajko wrote: post #54

Earlier quoted context omitted.

Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time le…

I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both…

[deleted]

Re: The Opposite of Documentation is Superstition (2020)

#72

Post by VectorLock »

martin-t wrote: post #49
nox101 wrote: post #4

Seems to me documentation can also be superstition if it's out of date. I wonder if LLMs can generate docs at any reasonable level of usefulness and accuracy Speaking of which, I just tried using ChatGPT to create a React app with typescript and rollup. What it generated didn't work (got errors). Of course I could tell it the errors and it fixed them but it suggests they aren't yet ready to write accurate docs

I inherited 100k LoC "documented" by an LLM. LLMs can put into words what a programmer can infer from struct definitions, function signatures, names and even taking a cursory look at a function body. LLMs cannot retroactively find out the _why_ of design choices. If you don't document the reasons behind decisions while making them, they'll be lost, which is exactly what leads to superstition. As a result, changing co…

Someone at work recently introduced a thing that would create git commit messages from code, completely negating the necessity of the programmer to provide accurate not-contained-in-code context. If they weren't across an ocean I would have shook them by the shoulders until they understood.

Re: The Opposite of Documentation is Superstition (2020)

#73

Post by mejutoco »

Animats wrote: post #15

I've called this ritual-taboo programming for decades. It happens for user interfaces and APIs when the documentation is absent, or only consists of examples. If there's no reference documentation, everything is a copy of something someone else did. Nobody understands how it really works. Now, for some interfaces, this isn't too bad. Most people don't know why US AC power plugs are polarized, or what the ground prong…

> Especially in the Javascript era. It's worst in languages that don't have data declarations. There's no place to properly document the data.

Typescript is very common too. It has all the types needed to document the data. And vscode understands all the references and navigates through them by default.

Re: The Opposite of Documentation is Superstition (2020)

#74

Post by danielheath »

jajko wrote: post #54
brabel wrote: post #44

Earlier quoted context omitted.

> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: this is the exact wrong way to do it. A programming interface should be easy to use and "self-documented" to some extent (by, e.g. using the type system as much as possible to make bad states unrepresentable), but only very simple interfaces are usable that way.…

Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time le…

It’s not that I’ll assume the internals are not going to change.

I just don’t trust the docs to be accurate anymore. The implementation contains an accurate description of what it actually does.

I still read the docs… with a grain of salt.

Re: The Opposite of Documentation is Superstition (2020)

#75

Post by fao_ »

lelandbatey wrote: post #42
IgorPartola wrote: post #20

Earlier quoted context omitted.

How do you view self-documenting interfaces? Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? I think there are interfaces that need to be usable assuming documentation will not be read. These are of course user interfaces, not necessarily APIs. But if you are creating something like a library of basi…

> How do you view self-documenting interfaces? > Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? Have you ever read the manual for the tools used to build the building that you live in? A manual for the trowels, tape, mud, and drywall that built and makes up your walls? Or a manual for the Romex in t…

> You browse the web constantly, so you do it without thought. Not so with your taxes, despite their similar constance and ubiquity, because they are not constant and thus haven't had the same abstractions engineered into their very DNA.

In the UK, the government automatically takes tax out of my income and tax is indicated as part of my pay cheque. It requires absolutely no thought from me.

Re: The Opposite of Documentation is Superstition (2020)

#76

Post by jajko »

danielheath wrote: post #74
jajko wrote: post #54

Earlier quoted context omitted.

Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time le…

It’s not that I’ll assume the internals are not going to change. I just don’t trust the docs to be accurate anymore. The implementation contains an accurate description of what it actually does. I still read the docs… with a grain of salt.

Man, sometimes I would give some gold for some documentation, even 10 years old. Half-irrelevant, doesn't matter. At least something. Sometimes, I don't have even that. That's what drowning in complexity looks like since there are some many question marks and often nobody anymore to answer them.

Even stellar code just tells me whats going on. Doesn't tell anything about why its happening, what consequences does it have in other systems, what are the overall constraints of this domain etc.

I agree generally too long comments aren't best, or even just non-flexible rules. But denser the logic is, the more spread its across multiple systems and environments, the more info the better.

And to be changing some dense code and completely ignoring comments just next to it describing them... that's just rude to be polite. Shows who is a team player and who isn't. Trust me, if you want to make friends and have some respect in some long term team, this is one sure way how to do it.

Re: The Opposite of Documentation is Superstition (2020)

#77

Post by crazygringo »

Animats wrote: post #15

I've called this ritual-taboo programming for decades. It happens for user interfaces and APIs when the documentation is absent, or only consists of examples. If there's no reference documentation, everything is a copy of something someone else did. Nobody understands how it really works. Now, for some interfaces, this isn't too bad. Most people don't know why US AC power plugs are polarized, or what the ground prong…

> For more complex interfaces, it means that many functions will either be misused or undiscovered. This is the source of the plaint that only 10%-20% of a product's features are used.

That's not a complaint, it's an observation, and it's not due to discoverability. It's because products are made for many kinds of users with many kinds of needs, and their needs often don't overlap a ton.

I probably don't use 99% of what ffmpeg can do, but it does everything I need it to. And with word processors it's still the same principle -- I've never in my life needed to do a mail merge, or apply a watermark, or 100 other things. But other people do. And it has nothing to do with discoverability.

Re: The Opposite of Documentation is Superstition (2020)

#78

Post by ChrisMarshallNY »

eddd-ddde wrote: post #69
pasc1878 wrote: post #51

Earlier quoted context omitted.

But it covers only how to use a function if you know what the system is meant to do or know which function to call in the first place. You need some overalls documentation to explain the concepts and how to put things together. When the user understands that you can use in-code documentation but even then only if you need to use one function at a time - there needs an explanation of how to put things together.

Integration tests? They show how the system works as a whole, and they don't go out of date.

They are, indeed, useful.

I usually create full-fat test harnesses[0] for my stuff, as that gives a totally realistic implementation example.

But I think having a well-written README is more likely to be useful.

API/implementation documentation (whether docs or tests), are much more likely to be read, than end-user docs.

[0] https://littlegreenviper.com/testing-harness-vs-unit/

Re: The Opposite of Documentation is Superstition (2020)

#79

Post by IgorPartola »

dingnuts wrote: post #67
jajko wrote: post #54

Earlier quoted context omitted.

Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time le…

I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both…

There are situations where a long comment is warranted. Sometimes you have to drain the septic tank and it’s a nasty process. Better do it once in a contained environment wearing gloves and a mask. Document why this code sucks. Explain what it does and why.

But in most cases explaining what your code does is like explaining a joke: if you have to explain it, it’s probably not very good.

Re: The Opposite of Documentation is Superstition (2020)

#80

Post by IgorPartola »

sahmeepee wrote: post #43
IgorPartola wrote: post #20

Earlier quoted context omitted.

How do you view self-documenting interfaces? Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? I think there are interfaces that need to be usable assuming documentation will not be read. These are of course user interfaces, not necessarily APIs. But if you are creating something like a library of basi…

> Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? For niche situations, yes, e.g. different browsers having different keyboard shortcuts for hard refresh. It's quite common for people to assume they know how to do it in one browser because they knew the shortcut in another, but when they just get a normal refresh they don't realise their…

You have read the actual manual for your browser? Multiple browsers? You didn’t google for the answer on how to refresh the pages? Somehow I just don’t feel like this is the literal truth.
Post reply on HN