5 ms·

The problem with "documentation" in commercial code is that nobody reads it. Any "documentation" that isn't embedded in code will never be opened again. Any "

• llm_trw 2y ago
  Here's another: literate programming. If it's good enough for Knuth it's good enough for me.
  • oersted 2y ago
    I tried to do it seriously a number of times. Perhaps I am doing it wrong, but my productivity drops like a stone. Writing down your thoughts as you go and maintaining them takes serious time. The romantic notion of writing (and reading) code like a book is appealing, but writing books is hard and arduous, it cannot be underestimated as a craft on its own right, and there is coding to be done. There is also the question of structuring the literate code. Telling a story of how you are building it or explaining how it works has a very different flow and order to how code is usually structured for good maintainability. Please correct me if I’m wrong, because I would love to dive into it, but I don’t think there has ever been any major piece of software developed following literate programming (at least as Knuth envisioned it). I also don’t think there is any significant book that contains a sizeable working program embedded in it throughout, that can be compiled and executed as-is. In practice Knuth was most concerned with embedding short code snippets in his papers and books. Having the whole thing be an actual compilable program was secondary, and it was mostly short academic proof-of-concept prototypes and algorithms. Don’t get me wrong, I love the concept, that’s why I have given it multiple serious tries over the years, likely I will again, and why I think I have some insight of what happens when you use it for “real-world” work.
    • llm_trw 2y ago
      NoWeb can support multi-thousand page documents which can compile to tens of thousands of lines of code. I used it at a deep tech startup I worked a number of years ago to document the theory behind why the code was doing what it was. Doubly useful since I could just use a regular bibtex citation system for papers which had done some part of what we were trying to do. My code became the defacto technical onboarding document, still in use today, despite the fact that none of the code in it has been updated since I left. For examples you can read: http://brokestream.com/tex-web.html http://brokestream.com/tex-web.html TeX is written entirely in WEB.
      • oersted 2y ago
        Thanks for the insight. Just to be clear, writing documentation after the fact with lots of code snippets is obviously good and is standard practice. You can take the next step and ensure that the entirety of the code is in your documentation as snippets. This usually doesn’t make much sense, there’s lots of code that it is not worth explaining in a literate style. And what’s the point of the documentation containing the whole program if it is written after the fact and you already have a standard more maintainable codebase as the ground truth? The fact that your literate code didn’t get touched says a lot. To me the name Literate Programming implies that you write the code in a literate style from the outset. If you make it literate after the fact it is just normal documentation with snippets isn’t it?
        • llm_trw 2y ago
          >The fact that your literate code didn’t get touched says a lot. The fact it's still used 5 years later without any of the code still being in production says more. >To me the name Literate Programming implies that you write the code in a literate style from the outset. This seems like a fundamental misunderstanding of what it means to write. You should perhaps look at how people who do it for a living write books or articles. The final document has little to do with what you spend most your time editing. I absolutely hacked on the tangled source code of the program when trying to fix bugs or extend capabilities. Once I knew what I wanted to do I put it back in the literate program, usually finding a lot more bugs in the process.
  • GuB-42 2y ago
    Knuth is not the average programmer by far. And I am not talking about coding skills. Knuth is a writer at heart. He was also from a time where writing code on paper was the norm. Literate programming is good for Knuth, but maybe not for most coders today, who grew up on fast computers and IDEs.
    • llm_trw 2y ago
      >who grew up on fast computers and IDEs. >>When I was a child, I spake as a child, I understood as a child, I thought as a child: but when I became a man, I put away childish things.
• mycall 2y ago
  Depends how you write code. When I use Semantic Kernel, my KernelFunctions include a well-defined documentation for the inputs and outputs, then using the System Prompt you can provide the concepts and glue between the various plugins. It is the function specification as a whole. Precision is important, although GPT is not yet perfect -- perhaps in another year or two it will be.
• exe34 2y ago
  my favourite documentation is minimal running code examples. give me example inputs to get the job done - i.e. not just "inputs: x is a y", but actually create a minimal version of y and show it going into f(x) and coming back out as a genuine object (as opposed to a mock) that I can inspect/prod until I understand what's happening.
• ransom1538 2y ago
  I prefer when developers and project managers create massive google docs for specs and descriptions. Double points if you share the document with only a handful of favorite employees. Also, ignore all requests to get permission to this document. Eye roll in all meetings if someone hasn't read this document. You can get to god mode if you hide comments around the doc.
• YawningAngel 2y ago
  Lots of people, myself included, read documentation.
  • ks2048 2y ago
    Ditto. The problem is self-reinforcing: people don’t read docs because the docs are bad… we don’t spend time on docs because no one reads them…
    • sshine 2y ago
      Not only is it self-reinforcing: It is inevitable because some competent programmers deliberately don’t comment their code, read comments, or delete other people’s comments when they are stale.
    • sshine 2y ago
      > The problem is self-reinforcing: people don’t read docs because the docs are bad… we don’t spend time on docs because no one reads them… I don't get discouraged from writing docs because nobody reads them. I'll read them. But I do experience another similar self-reinforcing problem: If other people don't read or update my docs, the docs begin to lie.
  • sshine 2y ago
    I personally read and write a lot. I track things in git messages by cross-referencing issues, and I comment my code. But my point is: when you have a cultural divide among competent programmers on whether to comment, not commenting game-theoretically wins, because the outcome where you have comments that get updated some percent of the time is worse than not having those comments. Instead, embed what you want to say in a comment in the code itself, or in a test. Documents your libraries and APIs if they are used by people outside your team.
• intelVISA 2y ago
  Good code is fairly self-documenting, but alas.
  • axelfontaine 2y ago
    That may be true for the "what", but certainly not for the "why".
    • intelVISA 2y ago
      Why is best inferred from context imo, otherwise it's a smell for a system with too much scope.
      • consteval 2y ago
        You can't context-out business requirements, IMO. Also code can have bugs. You need more formal requirements definition so you can compare behavior to requirements so you can find out bugs. Otherwise, how do you find the bugs?
  • planetafro 2y ago
    I can't even count how many times that I've had the DRY vs. verbosity of code conversation in trying to norm a team. I'm in the camp of a little verbosity and repetition for the sake of clarity is worth it.
• selfmodruntime 2y ago
  This is pretty much why Rust has doctests. You include a small test in your docstring.
  • enraged_camel 2y ago
    Elixir as well.
  • sshine 2y ago
    Executable tests in Rustdoc are amazing. For those not involved, they are run when you write `cargo test` and they are included as markdown code blocks in your crate’s documentation. They’re not an excellent place for extensive testing. But they are super useful for making sure your documentation examples are updated and functional. #![deny(missing_docs)] is also a great way to ensure you don’t forget to document things.
    • jampekka 2y ago
      Doctests are indeed a great format for documentation. They are automatically checked for currentness/correctness, aren't ambiguous like natural language and are close to the implementation. But I have the feeling that doctests aren't seen as documentation the way that is often desired in the documentation discussions.
• xtiansimon 2y ago
  Not at any level? My imagination is reeling—I’m thinking of Cold War era Spy Novels describing siloed groups who don’t know what any other group is doing. Each is laser focused on their own tasks and everything is a tactical choice. It’s the great reveal in the Movie adaptation when the separate threads come together and the grand national strategy is revealed. And now I’m also imagining the comedy versions of this genre, where the reveal has no purpose. At some level there is _structure_, and it can be communicated. If for no other reason than to validate the evident structure in code. > “…sitting at the same table as the almighty coding knights? […] Remove documentation…and your products cease to exist, their inner workings left to the imagination of…” The author finished the sentence with “users”, but who are they talking about? Those coding knights and their imagination which sort of parallels my Spy genre example. That said, the article seems a bit naive about the depth and breadth—reads like Ra-Ra.
  • remoquete 2y ago
    Author here. What do you mean by depth and breadth?
    • xtiansimon 2y ago
      -1, huh. Take my opinion with a grain of salt. Today I work for a small private firm, but years ago I worked in a corporate job (with tech writers). I drank the Kool-Aid. I believed the work I was doing was important and critical because someone up the vertical decided it was and they hired someone who hired someone who hired me to do a job--its corporate world. The tell for preaching to the choir, what triggered my response, are the hyperbolic strong statements ("products cease to exist", "your business don’t crumble overnight", "failures are dramatic") which sound defensive. The rest of the blog post reads as defining what exists and setting standards, and further explanation of why it's all important. This is the breadth and depth. What I'm not reading are on/off-ramps and shortcuts that all of the developers who disagree about the mission critical position of documentation would regard as sensible accommodations. Today I work in a small firm and we need documentation. What I learned from underpaying small business is documentation is important and has a role (otherwise our small firm wouldn't waste our time on it). But if I took the position argued here, I would be told I was wasting time, that I should focus, get it done, and move on my job tasks. If you're working closely with writers, then you need to believe what they're doing is important without being told. If you don't believe this, then maybe your role does not need documentation (yet? or your group is small enough and people like the job security or you're just overworked, or something else). When I'm working collaboratively and I hear people tell me what I'm doing is not important, I have to believe there is some truth to it. A limit. Good luck in your work.
• MrHamburger 2y ago
  code-as-docs will never tell you why method or a module exist in the first place.
  • sshine 2y ago
    The commit history will.
    • MrHamburger 2y ago
      Well from my experience, people who does not write comments are not keen on writing commit messages either. "Some updates", "Module ABC" "Changes"
      • sshine 2y ago
        It seems like the “why” is eternally lost on us in this scenario. If I could wave a magic wand and make all the colleagues verbalise what they’re doing, I would. In the meantime, I’ll take the downvotes for pointing out that it’s fundamentally caused by a cultural gap, not just “those who don’t get it yet, and those who do.”
      • simonw 2y ago
        This is why I like all commit messages to link to an issue thread somewhere (such as GitHub issues). The great thing about issue threads is that you can add more context to them later on - unlike commit messages which are frozen in time.
        • MathMonkeyMan 2y ago
          And, again, issue threads are only helpful if the people corresponding in them are good communicators who put in the work to leave a legible record of what happened. Many Github issue threads that I read are incomprehensible. The thread is not where the story is (it's in the memories of the people involved). Explaining is work. This is why they make kids write reports as assignments in school.
• simonw 2y ago
  If people aren't reading your documentation it means they don't trust your documentation. The solution is to build that trust, by building a culture of active documentation maintenance. My favorite trick for that is to keep the docs in the same repo as the code and actively enforce relevant documentation updates as part of the code review process. Once developers learn that new code cannot land on main without accompany documentation updates they learn to trust that documentation pretty fast.
  • sshine 2y ago
    > My favorite trick is to [...] actively enforce [...] If active enforcement were an option, and it led to success, I don't imagine there would be a problem. My favorite trick is to tell people really nicely they should write comments (preferrably doc comments on internally exported interfaces). Yet, they don't. And so we're back to the dilemma: If a significant percentage of competent programmers choose to not comment their code, or update the comments that are in the code, the comments will lie over time. And so it is probably better to not include them. We haven't even reached the point in the conversation where we ask "But why is it you, dear competent programmers with decades of experience, think we should continue to minimize the amount of comments with good conscience?" or ask "Why is it, dear project managers, that we tolerate a total lack of communication through any other means than executable code?" And the answer is probably: Because a lot of autists produce a lot of valuable code, and they don't like to talk if they can avoid it, and we value their work and relay what they made to the wordy-word people. > If people aren't reading your documentation it means they don't trust your documentation. I don't trust your documentation unless there's alignment among developers. Alignment is a luxury you don't get in legacy shops.
    • simonw 2y ago
      If people don't add documentation to their PR, I add that documentation to the PR for them (under my own name as a separate commit), then land the code. Do that often enough and people get the idea that documentation isn't optional.
    • jampekka 2y ago
• btbuildem 2y ago
  I read the article as referring to documentation for end users -- not internal documentation / comments written by developers who thought they knew what the code they wrote was doing.