Common Coding Misconceptions — The Commenting Conundrum
So today, in my bleary-eyed morning-zombie state, I explored an issue with some code written by a former-administrator-turned-architect. I misread the code, made a tentative conclusion, and wrote the team about it.
I was mistaken. The code did not operate as I thought, and the former administrator corrected me. During our conversation, the statement was made: "It's self-documenting. It's Perl." Now, I'll assume he was speaking in jest, and I responded accordingly. But this is not the only person in the systems field who has expressed this notion to me with various levels of sincerity (although not just with Perl).
I would like to say for the record:
CODE DOES NOT, CAN NOT, AND NEVER WILL SELF-DOCUMENT!
If you think otherwise, then you obviously have never had to spelunk through gnarled code left behind by some long-gone administrator/programmer, all in vain hope of trying to adapt or maintain the aging code base for modern needs.
The ACM has a great article on this topic. What is odd is that I found this article this morning, before I delved into the code and misread it, and before the "self-documenting" conversation occurred.
Here's a few points to keep in mind when coding, particularly if you are a sysadmin coding for administrative needs:
- You will NOT be around forever.
Someone else is likely going to use/revise your code at some point. Even if you plan on being in your position forever, reality will disabuse you of this notion by placing you under a bus, giving you a promotion, sending you a pink slip and severance check, filling your IT-widened behind with cancer, or in some other way smacking you down. - Your process is NOT "The Process."
Sure, that algorithm you devised is really efficient and was quite brilliant of you. That doesn't mean ANYONE else who follows you will understand it. - Clear and simple code is NEITHER clear NOR simple.
Sure, most languages have simple logic structures that are pretty much common to all of them, but the overall slurried context of procedure, steps, variables, cases, et cetera can confuse even the best professional. - If you think there are enough comments, there likely ARE NOT enough.
Sure, wading through comments might seem like a hassle to you while developing, but they are precious as The One Ring was to Smeagol when you are trying to debug someone else's code. Comment until it hurts, then re-read them and you'll probably need to add more. - Changes are important, too!
If you aren't using CVS/RCS, then keep track of changes in the form of comments! A change summary at the top of the code, along with change-specific comments where required. You moved from byte-by-byte processing to block processing to be more efficient? Say so, to prevent subsequent admins from finding out the hard way. - Comment, you BASTARDS!
I don't care if it is a three-line life-simplifying shell-script that passes arguments in a complex fashion to a command, or an operating system. COMMENT! COMMENT COMMENT COMMENT COMMENTCOMMENTCOMMENT!
This programming tip brought to you by SPANC (Systems Professionals Against Non-commented Code), the organization that will bring commenting to code by any means necessary...