You just described my most fitting persona, one which wasn't mentioned in the OP: the Refactorer (or less glamorously, the software janitor). Reducing complexity is among my favorite programming activities. Nothing like calling it a day after disentangling some chunky piece of over-engineered object-oriented spaghetti, leaving the codebase a few hundreds LOC lighter and all test lights flashing green.
I think what he's saying is, after all that, you're still probably producing shit, that no matter how awesome you are, whoever ends up tending to your pet Frankenstein after you've moved on is probably still going to spend half their time cursing your existence, if they weren't part of the project from the beginning.
And that's only if you're good enough in the first place so that "finishing" is actually worth the effort, rather than starting from scratch using your code as the blueprint for the new and improved 2.0 spec. This requires not only that you be good, but that you get lucky: that you've accurately predicted the stack that your ops team will be pushing to standardize on in 2 years, that there's enough expertise in the language(s) you used to justify its continued use, that management hasn't decided to switch everything to Windows + .NET because "support", that every one of the OSS libs that you've pulled in all happen to be licensed under the three particular OSS licenses that legal decided to approve after that recent switch to a "whitelist" policy, that the company services you were forced to integrate with when you started haven't been shitbinned, that the new lead developer on the project doesn't have aesthetic problems with the way your code is organized, and so on. All of which usually mean "rewrite!", and few of which you have much control over. At the end of the day, it doesn't matter whether it's your fault or not, the people evaluating your work will still consider it "shit" because it's not usable anymore, and nobody loves the project enough to bother figuring out how to patch it up.
IMO, though, the real reason we all tend to produce shit (and then throw it out later) is actually missing from this otherwise excellent four-part breakdown: documentation. And I'm talking real, detailed, explicitly human-centric documentation that's more than just class/function level comments or a user manual. Lately I've been dealing with several attempted tech consolidation tasks as part of a several-tier acquisition (big fish swallows little fish, bigger fish swallows entire lake), and it seems that no matter what size the company is, nobody in software ever fucking documents anything well enough to reuse it, even when they're developing services that are explicitly intended to be consumed by other groups. The resulting duplication of effort is ridiculous.
Good internal documentation needs to start with the starter, end with the finisher, and be taken seriously by everyone in between. It should be considered almost as important to a project as the code itself. It needs to explain how to use the system, how to integrate with it, how to debug common problems, where the pain points are, how the system is architected, why certain decisions (especially tradeoffs!) were made, and more. Done right, good documentation can make up for some pretty bad code, and make sure that a project is actually maintained rather than thrown away.
Spot on—wish I could upvote each sentence of your comment.
Everyone knows code readability counts, because it's “read much more often than it is written”. Same on a larger scale—the project is built once, and then maintained for years and decades (especially in “enterprise” environment). So you should optimize for maintenance—that is, write docs.
It really puts me out that no one else in the team or management appears to take documentation seriously. Is this ‘job security’ or general negligence, I don't know. I think either your primary concern is project success, or it is your job and money. If it's the latter, then of course why would you write docs—just bang out something that works for client/employer, you'll get paid and it'll be harder to fire you.
Or maybe it's management problem really and I shouldn't care.
I think it's a short-term vs. long-term problem: everyone's focused on hitting their milestones and the problems that will be caused by the bad documentation won't manifest themselves until later. It's kind of a "technical debt" situation.
+1 for bringing up documentation. Good documentation without code is valuable. Good code without documentation ... probably worthless (unless it's clean enough to read, which is rare for production code once you've killed all the weird edge-case bugs).
