But I think turned out to be a bit too much effort for the benefit (java docs!).
That depends on the circumstances. On the big, long-lifetime systems that I used to work on — military, commercial aviation, satellite, medical — the original coding was typically less than 10% of the programming effort. Navy systems have a particularily long lifecycle because the big ships only do a major refit every 10 years. I’m not aware of any specific examples, but imagine your code being maintained or enhanced by someone who wasn’t born when you wrote it.
The only real “silver bullet” we’ve ever found in the computer biz is embodied by Open Source — code that’s read by a lot of people. “Given enough eyeballs, all bugs are shallow.” Doing everything you possibly can to make your code easy to read is an immensely valuable thing to do; it gives the bullet a gold core and diamond tip.
Btw, I have huge respect for Don Knuth, but some of the code he wrote for his own systems like TeX was pure German-American spaghetti. He got better.