4 ms·

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. I

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 is for. Electricians have to, but users do not. 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. On user interface design, the classic is "Tog on Interface", Bruce "Tog" Tognazzini, 1992. That's from the Mac UI era. A more modern take is "The Gamer's Brain", by Celia Hodent, designer of Fortnite's UX. Software internal documentation seems to suffer today from a mindset that comments are unnecessary and waste space. 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. Rust has good conventions and tools for documenting data. There's a well defined place where the documentation for each structure and field goes, and reasonable tools for checking it and turning that into documentation. If you fail to do this, when you publish your crate on crates.io, the documentation pages will come up blank, which screams "loser". Rust is weak on function parameter documentation. There should have been a defined place where each formal parameter gets a comment, which then appears in the documentation of the call. Most other languages don't take such a hard line. More should.

fiforpg 2y ago
> ritual-taboo programming I like to think of it as "cargo-cult programming", along the lines of the well-known essay by Feynman.
- Animats 2y ago
  Cargo cults don't work at all. Ritual-taboo systems sort of work but are suboptimal.
  - michaelcampbell 2y ago
    Only if that's how you make the distinction between the 2. Copying something hoping it will do something you want because it did do that thing elsewhere, without understanding at all how or why it works is essentially the definition of CC programming.
    - andrewflnr 2y ago
      Honestly not a bad delineation, considering what the original/actual "cargo cults" were.
  - KronisLV 2y ago
    > Cargo cults don't work at all. The people who take DRY and SOLID as absolute rules might create codebases that will be harder to maintain, but probably won’t go up in flames. I think cargo cults absolutely do work, same as how people pick Nginx “because it’s fast” while they might need to consider that their Python API probably wouldn’t be bottlenecked even by Apache2 (depending on what you’re doing Nginx might still be the right choice, but for different reasons). Similar to how people might lean towards either Java or .NET for a plethora of shallow reasons - either will work for most problems, so the choice will be good even if the reasoning behind it might be bogus. Same for AMD vs Intel or AMD vs Nvidia etc. Unless you need to be web scale, then the right answer is clearly MongoDB. /j
IgorPartola 2y ago
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 basic math functions I would rather read your code than your docs. Some of the worst docs I’ve read lately have been for ffmpeg and mp4box. The former sometimes straight up has things like “so one guy tried this and it worked for him so we recommend you try it and see how it works for you”. The latter has like 4 examples with no explanation of what you are looking at or how to make anything else work. The project used Stack Overflow for their docs because nobody can really figure out what to do with it right away. I’d rather take readable code in this case over the terrible docs.
- throwaway14356 2y ago
  writing great documentation is extremely hard. sometimes it is so well done you only notice it in how fast and easy you progress. the funniest opposite was documentation i wrote myself but turned out to complicated for the future self. i kept thinking, what is this guy on about?? it assumed the reader knew all kinds of things i didn't and it made effort to explain the obvious.
- lelandbatey 2y ago
  > 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 those walls? A manual for the concrete foundation of your building? No? That's because using/depending on those things doesn't require nearly anything of you; you stand on the floors and lean on the walls without thought. 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. But even things like buildings/floors/doors with that level of "no need to think about them" only afford that to you based onto their frequent use. Few other pieces of software afford that same consistency. With time though, they will. I think we'll see a lot of software grow to be everore of a "skin round a spreadsheet", especially as we comoditize the few remaining frontiers of UX design (e.g. mobile devices) in the same way as desktop design has converged on common patterns like the chat-log-and-history, the search bar, the photo gallery, the text editor, and the spreadsheet.
deleted 2y ago
[deleted]
tempodox 2y ago
It's always the same problem: The work generated by doing documentation, including the possible need for specialized talent, is quite directly perceivable. The work generated by the absence of documentation is more under the radar and disguised as “cost of doing business”, which makes it harder to convince the anti-documentation crowd. Not to mention the “job security” aspect of everything being in the heads of the ICs.
- hiAndrewQuinn 2y ago
  In other words, it's a principal-agent problem. The ICs (agents) tasked with creating documentation see it as extra work with no immediate payoff for them, and indeed even some long term downsides; the org (principal) bears the hidden costs of its absence - inefficiency, delays, trouble when Mr Magic Touch switches jobs. There's nothing special in kind about this, it happens in all industries. The fix? Stop leaving it optional. Tie documentation to performance reviews, bake it into deliverables, reward teams for knowledge-sharing. If you can’t convince them with logic, align incentives so ICs can’t ignore it. It's either that, or accept that you believe ICs have better things to do with their time. But make a conscious choice either way, I'm begging you!
  - onemoresoop 2y ago
    Forced documentation by ICs could be poorly written, leave things out or quickly sync out of date. I think there should be a dedicated team tasked with managing this documentation.
    - hiAndrewQuinn 2y ago
      So long as you have the budget to hire for that, the world is your oyster. Alternatively you could take the risk and pass the savings on to the consumer - it's all up to you, my friend.
sakex 2y ago
I agree to some extent, but I'd say it depends on the programming language. For instance, in Python, you absolutely need documentation because you don't know what type is expected, what different values can be passed or even the optional kwargs etc. It's also very common to pass strings as parameters when one should be using enums, which means you can't know what are the possible values without having the doc or diving into the code. In Rust however you can get away with way less documentation because the type system and signatures are self explanatory. And if you're doing things right, the set of values you can pass to your function is limited.
- tremon 2y ago
  On the other hand, with Rust and Haskell you absolutely need type constructors to be easily discoverable. If open gives me an Fd, but the library function accepts a Stream, I shouldn't need to spend hours wading through sparse documentation to find how to convert between the two. Something like Hoogle becomes a necessity if you want your type system to replace the need for documentation.
makeitdouble 2y ago
These are all valid point if documentation is the only way to get the info. They key point to me in TFA: "The feature is a black box" This doesn't apply to software internal documentation. It's not a black box and you can give any deep you want to know what is and isn't implemented, what has explicit tests and who wrote it. Whether comments on those are a waste of time of not will come down to how long it will take to write useful comments, how long it will take for the reader to understand the class/function/method otherwise, how much maintenance will happen on the comment itself after it's written, what it will cost when it will "rot", and what else (e.g. tests ?) the dev could do with all that time.
mejutoco 2y ago
> 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.
crazygringo 2y ago
> 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.

fiforpg 2y ago

> ritual-taboo programming I like to think of it as "cargo-cult programming", along the lines of the well-known essay by Feynman.

Animats 2y ago
Cargo cults don't work at all. Ritual-taboo systems sort of work but are suboptimal.
- michaelcampbell 2y ago
  Only if that's how you make the distinction between the 2. Copying something hoping it will do something you want because it did do that thing elsewhere, without understanding at all how or why it works is essentially the definition of CC programming.
  - andrewflnr 2y ago
    Honestly not a bad delineation, considering what the original/actual "cargo cults" were.
- KronisLV 2y ago
  > Cargo cults don't work at all. The people who take DRY and SOLID as absolute rules might create codebases that will be harder to maintain, but probably won’t go up in flames. I think cargo cults absolutely do work, same as how people pick Nginx “because it’s fast” while they might need to consider that their Python API probably wouldn’t be bottlenecked even by Apache2 (depending on what you’re doing Nginx might still be the right choice, but for different reasons). Similar to how people might lean towards either Java or .NET for a plethora of shallow reasons - either will work for most problems, so the choice will be good even if the reasoning behind it might be bogus. Same for AMD vs Intel or AMD vs Nvidia etc. Unless you need to be web scale, then the right answer is clearly MongoDB. /j

IgorPartola 2y ago

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 basic math functions I would rather read your code than your docs. Some of the worst docs I’ve read lately have been for ffmpeg and mp4box. The former sometimes straight up has things like “so one guy tried this and it worked for him so we recommend you try it and see how it works for you”. The latter has like 4 examples with no explanation of what you are looking at or how to make anything else work. The project used Stack Overflow for their docs because nobody can really figure out what to do with it right away. I’d rather take readable code in this case over the terrible docs.

throwaway14356 2y ago
writing great documentation is extremely hard. sometimes it is so well done you only notice it in how fast and easy you progress. the funniest opposite was documentation i wrote myself but turned out to complicated for the future self. i kept thinking, what is this guy on about?? it assumed the reader knew all kinds of things i didn't and it made effort to explain the obvious.
lelandbatey 2y ago
> 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 those walls? A manual for the concrete foundation of your building? No? That's because using/depending on those things doesn't require nearly anything of you; you stand on the floors and lean on the walls without thought. 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. But even things like buildings/floors/doors with that level of "no need to think about them" only afford that to you based onto their frequent use. Few other pieces of software afford that same consistency. With time though, they will. I think we'll see a lot of software grow to be everore of a "skin round a spreadsheet", especially as we comoditize the few remaining frontiers of UX design (e.g. mobile devices) in the same way as desktop design has converged on common patterns like the chat-log-and-history, the search bar, the photo gallery, the text editor, and the spreadsheet.

deleted 2y ago

[deleted]

tempodox 2y ago

It's always the same problem: The work generated by doing documentation, including the possible need for specialized talent, is quite directly perceivable. The work generated by the absence of documentation is more under the radar and disguised as “cost of doing business”, which makes it harder to convince the anti-documentation crowd. Not to mention the “job security” aspect of everything being in the heads of the ICs.

hiAndrewQuinn 2y ago
In other words, it's a principal-agent problem. The ICs (agents) tasked with creating documentation see it as extra work with no immediate payoff for them, and indeed even some long term downsides; the org (principal) bears the hidden costs of its absence - inefficiency, delays, trouble when Mr Magic Touch switches jobs. There's nothing special in kind about this, it happens in all industries. The fix? Stop leaving it optional. Tie documentation to performance reviews, bake it into deliverables, reward teams for knowledge-sharing. If you can’t convince them with logic, align incentives so ICs can’t ignore it. It's either that, or accept that you believe ICs have better things to do with their time. But make a conscious choice either way, I'm begging you!
- onemoresoop 2y ago
  Forced documentation by ICs could be poorly written, leave things out or quickly sync out of date. I think there should be a dedicated team tasked with managing this documentation.
  - hiAndrewQuinn 2y ago
    So long as you have the budget to hire for that, the world is your oyster. Alternatively you could take the risk and pass the savings on to the consumer - it's all up to you, my friend.

sakex 2y ago

I agree to some extent, but I'd say it depends on the programming language. For instance, in Python, you absolutely need documentation because you don't know what type is expected, what different values can be passed or even the optional kwargs etc. It's also very common to pass strings as parameters when one should be using enums, which means you can't know what are the possible values without having the doc or diving into the code. In Rust however you can get away with way less documentation because the type system and signatures are self explanatory. And if you're doing things right, the set of values you can pass to your function is limited.

tremon 2y ago
On the other hand, with Rust and Haskell you absolutely need type constructors to be easily discoverable. If open gives me an Fd, but the library function accepts a Stream, I shouldn't need to spend hours wading through sparse documentation to find how to convert between the two. Something like Hoogle becomes a necessity if you want your type system to replace the need for documentation.

makeitdouble 2y ago

These are all valid point if documentation is the only way to get the info. They key point to me in TFA: "The feature is a black box" This doesn't apply to software internal documentation. It's not a black box and you can give any deep you want to know what is and isn't implemented, what has explicit tests and who wrote it. Whether comments on those are a waste of time of not will come down to how long it will take to write useful comments, how long it will take for the reader to understand the class/function/method otherwise, how much maintenance will happen on the comment itself after it's written, what it will cost when it will "rot", and what else (e.g. tests ?) the dev could do with all that time.

mejutoco 2y ago

> 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.

crazygringo 2y ago

> 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.