I was asked to look over someone's code this evening on a personal project that they had been working on. So, naturally, I asked for their documentation and looked for code comments.
There were none.
I just emailed the organization back and told them not to waste my time - particularly when their 'software engineer' was still with them. Sure, it's pro bono work that was done. Sure, I was doing pro bono work. But really, life is too short for that kind of crap.
And thus begins my rant. It's not a new rant of mine, but it has become more refined over the decades.
I have encountered the issue. I've seen it on IBM System 36s, IBM 360 Mainframes right on up to that annoying device you have that makes sounds and vibrates when someone wants to get a hold of you.
Documentation is what separates the rabble from those that don't go extinct. If you watch this video (1 hr) - or you can take me at my word for this quote on the evolution from hacker to engineer:
A hacker can come up with solutions, but maybe they can’t look back after they’ve finished and realize how they came up with the solution. They just kinda poke at things until they get something that works.
At some point, you level up and become a developer and a developer understands best practices. They’ve heard other developers say things like “you should put your scripts at the bottom of the webpage” … and you use those best practices to craft solutions but you don’t really understand beneath the best practices, beneath the abstractions.
An engineer is someone who can get things done, craft a solution — they understand the best practices, but they also understand why they’re using the best practices that they are … [they] move into an understanding of the platform as a whole.
Documentation is a best practice. Any time I see code without documentation, I see the work of a hacker - not a developer or engineer and I take umbrage when someone has the audacity to call themselves such (or is called such) without documenting anything. It tells me that they haven't been around long enough to look at their own code and be lost. It tells me that they don't care what kind of house of cards they build to maintain. It tells me that they don't respect the people that will come after. It tells me that they thought so highly of themselves that they thought their code would never need to be maintained. It reeks to me of 'amateur', no matter how good the code is. It tells me that there was no process involved with the code, that there were no best practices and that others let it slide.
Sure, documentation is not the most glorious aspect of Software Engineering or Software Development. It's annoying, particularly when you're doing software archaeology and have to document what someone else has been doing and hoping you get it right. Sometimes - most of the time for me - it's been my job to make sense of things that make no sense. This is the sort of nonsense that has countries other than the U.S. protecting the use of the word 'engineering' in a title, and years ago I reached the point where I wish the U.S. would comply with it.
If you're just going to write code and not comment or document anything, it used to be called job security. There are still niches of this sort of lazy 'protect my job' sort of stuff out there, but... for a project to survive in this day and age requires not bleeding money in wasting time figuring out how something should work. It's a financial hemmorage in the maintenance aspect of the lifecycle all because of a lack of best practices. It means that others that come in will have to spend more time (read: money) to figure out how to fix the perfect code you wrote.
Hiring a coder? Yeah, when you get the code, make sure it's documented. Or don't pay.