Worth reading even if you aren't a perl guy. Every language has this type of 'cultural markers' that set your expectations for a codebase by skimming a few files or just the project structure.
On that first dive into someone else's code[1], this markers are invaluable, they are the first cue into the author's mindset and background. They are a signal for future maintainers or collaborators. It's like stepping off the plane and hearing people around you speak with your own regional accent. Even if you've never been here before, now you know some of your knowledge still applies.
[1] Rule of thumb, if you haven't touched your own code for a long time, think of it as being written by someone else. You are not the same person you were when you wrote it.
> Rule of thumb, if you haven't touched your own code for a long time, think of it as being written by someone else. You are not the same person you were when you wrote it.
This is really insightful, most especially the part I italicized.
I can think of a few particularly embarrassing moments when I've dug through old code of mine and immediately thought "What kind of idiot wrote this crap?" followed by a brief moment of horror when the realization sets in that the idiot was me. :)
I think it would also make a fantastic addendum to this [1] discussion (and the article to which it is attached), especially since many new programmers often don't think much of code maintenance. Usually it's comprised of "I (or someone else) will eventually rewrite this." Then it enters production.
Oh gosh, yes. I've found that approach to be the most helpful. In a year (or three?), I know that I won't remember anything about what it was supposed to do. I'm pretty sure I'm stupid or forgetful. Probably both.
I like your assertion of documentation being a measure of progress. As dumb as it sounds, even if you're the only consumer of an API you wrote internally for some on-off application, documenting it thoroughly is a tremendous time saver. Granted, I still slip up occasionally, especially if it's a quick script of sorts, but I find more often than not that when I do regret not having taken the time to document something, it's (now) usually something deceptively simple that I wish I had better curated, because it eventually finds new life as part of a greater work.
Yeah, especially with one-off scripts I keep upgrading my machine / reinstalling to clean things up, and wondering wtf -nRT means and why I thought it was important. Something like half the time I google / manpage around for a while and find out it wasn't important, or assumed something incorrect about what it was trying to do.
I've started wrapping everything I do frequently in small bash scripts, and documenting what and why. Saves a lot of time when migrating to a new system, since I can glance and say "nope, don't need it" within a couple seconds, or remember why it was useful (and sitting in a cronjob somewhere) and reinstall the things I actually use.
Can't step in the same river twice is true in all domains, not just software. Admittedly with some languages it is worse than others, assembler and APL come to mind but same truth still applies.
[1] Rule of thumb, if you haven't touched your own code for a long time, think of it as being written by someone else. You are not the same person you were when you wrote it.