5 ms·
It's also generally useless. If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public
by aphextron 5y ago
It's also generally useless.
If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on, the software itself will have outlived its' usefulness. In an agile environment like this, keeping any kind of documentation up to date to be meaningfully useful is almost impossible without a dedicated team member.
- treeman79 5y agoI find having a few notes on the intention of a section is the most helpful.
- xwolfi 5y agoAnd a good set of unit tests can also cover what's the most useful, like edge cases, complex sequence, particular client flows, bug that actually happened in prod etc
- pithon 5y agoWriting is thinking and oftentimes just being able to explain in words what a thing does, should do, and should not do- has tremendous value as part of the design process before any code is written.
- billytetrud 5y agoDocumentation is not generally useless. Most code is used far longer than it's intended life, most code is read far more often than it's changed, and documentation can save literally hours and days of struggle. Word of mouth knowledge transfer is abysmal at keeping critical knowledge alive. Nobody ever knows anything about legacy code, and it's because no one wrote documentation. Please stop telling people documentation isn't important
- enraged_camel 5y agoI do agree that code is read more than it is written. At the same time, there's the adage: "treat your data as permanent, and your code as transitory."
- abc_lisper 5y agoUnder this kind of plausible argument, lie all sort of insects (bugs) in the dark. If people can make time to write tests, so should they write documentation. There is inordinate amount of frustration, productivity loss, and regression associated with having poor/outdated/no documentation.
- pfortuny 5y agoYou should think about all the cobol software out there and how your ideas contrast with it.
- saiya-jin 5y agoNot really. Maybe in your very narrow environment, but all the multinational corporations I've worked in past 17 years on, situation is way more complex. Software often outlives people who created them, sometimes even whole teams originally responsible for it. Suddenly you have a Pune team managing all environments including production, who have rather vague about yet another system thrown on them due to that smart idea called outsourcing. Sure they can change a thing or two, but corner cases can and often do bite hard. Code itself, while describing well what is happening, often doesn't contain much info about why. Or further effects of decisions. Full picture of whole integration involving 20 or 100 systems etc... Another issue in huge companies spread across the globe is the ability to actually connect with relevant team, and their reluctance to share crucial info. A job security political game is not foreign to devs in some cases. I've had my request for source code of one of our internal security libs, the cornerstone of all of our inter-app authentication, refused with justification that its safer for the company to not share it even within company. Mind you, the .jar wasn't obfluscated at all so JAD got me to almost-compilable version so that effort wasn't even half-assed. Man, I could spend whole evening telling stories how documentation can be great. Even incomplete, not completely up-to-date one can save your ass from time to time. And tons of time on top of that.