|Do you know where your variables are?|
Re^2: Why programming is so much more than writing codeby swngnmonk (Pilgrim)
|on May 08, 2007 at 14:22 UTC||Need Help??|
L~R, you nailed it. In retrospect, I shouldn't have posted the code, because everyone focused on it, which was besides the point.
I believe self-documenting code is something of a fallacy. Yes, it was easily recognized as a sorting routine. Yes, it sorted two array references based on out-of-order selection of sub-elements within each. We could all pick up on that.
The point I was trying to make was one about the value of taking the time to do things the right way. In this case, there's nothing explicitely wrong with the code. The problem is the fact that depending on people's ability to read code, no matter how self-documenting you make it, is a cop-out.
Like everyone else, I look at it, and go "sure, it's a sorting routine, sorting on sub-elements of two array-refs". But immediately, I think of the following questions:
And this is where I get annoyed. Because this sort sub isn't documented. Because the surrounding code isn't properly documented. Because the only documentation in this 500-line script is a couple of minor lines at the top about inputs and outputs. And in the end, this sub shouldn't even exist, because as far as I can tell, it's not being used.
Sure, code can be self-documenting, but to a point. This "self-documenting" code now requires me to spend far more time going through the code to figure out what is going on & why than it should. A car's motor is "self-documenting" in the same fashion - sure, I can figure out where everything is & diagnose the issue eventually, but the shop manual makes my life a lot easier.
And so, back to my original rant. It's not just about writing clean, easy-to-understand code. The 'easy-to-understand' part is not just code, it's comments. Documenation. Explanation. Motivations. I'm tired of the pseudo-macho justifications for not writing documentation. Write it. Because otherwise I'm just going to come back & drive you nuts, forcing you to explain why you wrote every last method the way you did.