71–80 of 103 posts
Tl;DR: If the environment is so volatile that the code is permanently broken reverse engineering doesn't work well. In such case the documentation may be your only recourse.
I've been using literate programming for 15 years on many projects. The largest and most visible one is Axiom ( https://en.wikipedia.org/wiki/Axiom ) which currently has many thousands of pages with embedded code. I've talked to Knuth. He claims he could not have implemented MMIX without literate programming. Literate programming is really valuable but you only understand that once you really try it. I gave a talk on…
Aside from that, i tend to agree with you, and i aspire to the same. Unfortunately laziness and time constraints often get the better of me, though.
Earlier quoted context omitted.
Software is hard enough as it is, without adding yet another hurdle to get from brain to .exe In my experience, it ultimately made it easier (see my big comment somewhere else here). It wasn't an obstacle to getting it done; it forced me to do what I really always knew I should - think about the design, make sure it made sense. Your comment also suggests that you might have missed a key point; it's not for you. It's…
> Your comment also suggests that you might have missed a key point; it's not for you. It's for other people (and also yourself in the future Most of the code you write over the years will be thrown away, sometimes before it's even released. So who is that text or literate comment for? :)
Ignoring the final truth that of course everything anyone ever makes will one day be discarded, that's not the case in some industries.
Additionally, we had inspections. Every so often, the customer (or rather, the alliance of customers) would send someone. He would pick a handful of requirements, and would then ask to see the complete chain from there; the breakdown of requirements from their level to the more functional level, the design that purported to meet those requirements, the code that implemented that design, the tests of that code, and then the tests of the original top-level requirements. We would literally get the relevant envelopes from QA, open them up and give him the paperwork. Everything signed, stamped, cover-sheeted and ready. In some industries, this kind of traceability is required and if you don't do it properly up front, trying to rebuild that trace afterwards is extraordinarily expensive.
See my other big comment here somewhere; in that case, the majority of the code was written once, delivered, and will be in use for a few decades. It was generally written correctly at the first iteration; the "literate" bit, which was the discussion of design etc., generally didn't change, so even when bugs had to be fixed, only the code changed to more closely meet that design (i.e. take out the bug) - the design was still the same, so the literate bit was still valid.
It is common in some styles of programming (and/or some industries) to effectively plan in advance that you'll write a dozen bad versions that don't work very well and only then will you write it correctly, or that you don't quite know what you're making (be it because the requirements just aren't available properly, or because you're not building to set requirements but just trying to make something that might sell) so you'll just make something and keep bolting bits on as you think of new things, but there are other styles where the aim is to get it right first time.
Others have already given the reasons about the downsides of comments. One other reason is: Most developers are terrible, terrible writers. It's one thing to imagine a profession of literate programming as practiced by Donald Knuth; it's another thing entirely to imagine it as practiced by the kind of people who are actually writing code.
TeX benefited from literate programming because it was written in a higher level assembly language. (Also, it was written by someone who liked to write books, and if a book was about software, he wanted to integrate the writing of the book and the software.) Better than literate programming is to write code that explains itself. Don't write two things, one of which executes and the other explains it; write an explana…
I can see how your code can explain the `what' and `how'. How are you going to answer `why' and even more important `why not'?
By `why not', I mean, a short description of why some reasonable alternative choices were not made. Eg why we use algorithm A and not B and not C.
TeX benefited from literate programming because it was written in a higher level assembly language. (Also, it was written by someone who liked to write books, and if a book was about software, he wanted to integrate the writing of the book and the software.) Better than literate programming is to write code that explains itself. Don't write two things, one of which executes and the other explains it; write an explana…
This is just me, but when I read through the literate programming book, and the hundred or so pages of literate code resulted in a program that could be replaced with a line of bash script, I decided that writing the program succinctly was more important than writing a novel to accompany it.
Because software changes so rapidly. Literate programming is based on the idea that you should explain what software does and how it does it in detail so that a reader can follow along and learn. That works great for TeX, which hasn't changed significantly since 1982. It works less great for say, Google/Alphabet, which wasn't even the same company last week. The general problem with documentation is that it gets out…
> most fast-growing startups have oral cultures where the way to learn about the software is to ask the last person who worked on it "Oral culture" - I like that euphemism. It's not disorganized, confused, poorly-planned, and glaring technical debt, no, it's "culture." > Most real-world products face new requirements on a weekly, sometimes hourly basis If your requirements are changing on an hourly basis, it's time t…
I've been using literate programming for 15 years on many projects. The largest and most visible one is Axiom ( https://en.wikipedia.org/wiki/Axiom ) which currently has many thousands of pages with embedded code. I've talked to Knuth. He claims he could not have implemented MMIX without literate programming. Literate programming is really valuable but you only understand that once you really try it. I gave a talk on…
Unless someone puts a comment above it? Literate programming isn't the only method of documenting code.
It makes it harder to make changes. The story you start telling is not what you end up with later, after you've completed all the non-trivial features and major assumptions have fallen through. Going back and fixing the story as you go along is expensive. Writing the story after it's done is too late - the business value is in the product's shipped functionality, not in the development artifacts. We have an alternate…
Your mention of commit messages resonates strongly with my own professional experiences, and I'm sure with many others' as well. Several months ago I started working with a commercial code base that has about 3 years of commits and over a dozen contributors, but very few inline comments. Navigating and refactoring it is usually a fairly reasonable process due to well-named symbols, module organization, and test cases…