It's an argument for clear code that's readily understandable by other people. It's not an argument for any particular technique for achieving that goal. I've never seen any programmer seriously suggest that code should be deliberately made difficult to understand.
I can't agree with you emphatically enough about this. Cargo cult commenting is one of the easiest ways to damage the readability of a codebase.
Comments should be an edge-case solution for explaining unusual quirks, not the go-to approach for explaining the entire codebase. Using comments to explain what the code is up to is like using exceptions for flow of control. A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows.
This point gets brought up a lot, but I'm not going to complain at all. In fact, just 5-6 months ago I used to be one of those programmers who would do
# gets the xml
def get_xml():
It took comments like this to help me realize just how silly the whole thing was. Now I write as much self-documenting code as I can, but comment as needed.
Comment should be "why I did this", and code should be "how I did this", some people just write in "what did I do" and walk away thought they have comment
I generally become aware that I should leave a comment whenever I write something that is less than trivial (but exactly less than trivial) to write/understand. Longish list comprehension? Summarize what it does. Nested function calls? Summarize why. Etc.
"A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows."
This may be a valid argument for modern languages like Ruby or Python. For 90s' coding standards however comments are even MORE important than the code itself. For Assembly and C programming and for low level graphics and physics algorithms proper naming of variables and functions are never enough for readable code.
I agree that comments should not be the "go-to approach for explaining the entire codebase." I hope you didn't think I was insinuating that in my comment. I was only trying to illustrate that in the absence of clear code, which many developers are guilty of sometimes, comments can be very helpful.
Sadly, I fear that comments won't help in that situation. They could, except that the solution depends critically on the developer realizing they're writing garbled code during the time they're writing it. I don't know about anyone else, but my code's never garbled when I write it. It only becomes garbled by magic, and only when I don't look at it for a few weeks. Or, strangely enough, the moment someone else looks at it.
Still haven't figured out a reliable enough garble detection mechanism that my employer's willing to pay for.
Nah I didn't think that at all, it was clear from the way you said "minimal commenting". I just have an axe to grind when it comes to comments of the form
// assign the integer value 10 to the variable x
x = 10
In our embedded systems class we were required to define all of our constants, just to add another level of description to operations. It definitely helped to navigate spaghetti code.
"I've never seen any programmer seriously suggest that code should be deliberately made difficult to understand."
Then you've not worked with some of the people I've worked with. The clever "it was hard to write, it should be hard to read" mantra has been thrown out by a few ex-colleagues trying to be clever, and a couple of them really meant it. Whether it was a hatred for others, or a misguided attempt at "job security", I'll never know, but some of these people do exist.
Often, however, the same effect is had under the guise of "clever hacks" - look how clever and awesome I am! What? Of course everyone else can read and understand this (they just have to understand that I compiled this with my own custom-built compiler I rolled myself on gentoo so I could squeeze out an extra .0001% improvement!)
"Often, however, the same effect is had under the guise of "clever hacks" - look how clever and awesome I am!"
Sometimes I write code like that. Then I delete it and write it the proper way.
Clever code is code you will not be able to understand in the morning.
There is Kernighan's adage
"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."
Indeed I fear I wrote code like that yesterday (a particular problem that, after talking to 3 other engineers, everyone agreed did not have a simple solution) that I am going to have to debug today. I am not looking forward to it!
useful thoughts. it reinforces my view that it's really the intent that bugs me. I've dealt with crap code, littered with comments like "I'm sorry, didn't know what I was doing, etc". The person/people knew they were in a tough spot. In other cases I've dealt with crap code with random comments like "Java sucks. Sun sucks. Everyone using Java sucks and is stupid - Ruby is the only true language, and it sucks that this is in Java" and "if you're too stupid to understand this, quit right now and tell so-and-so to go hire a real programmer".
Just... garbage attitude oozing through the code at every line - difficult to work with.
Maybe some awful programmers do advocate for it, but that doesn't really change my overall point. There is no serious argument in the community, at least, over whether code should be readable. The argument is merely about how to make it readable, and this story does not argue for any particular approach there.
One guy I worked with would do it to protect his bailiwick. He was intensely territorial, and knew that writing code so ugly that nobody wanted to even look at it, much less take the time to understand it, was an effective way to make sure that nobody else on the team would ever touch anything he wrote.
Sounds like "mortgage code"... code that is intentionally so complex that noone in the company other than yourself can maintain it, hence you end up with a job for life that pays your mortgage.
Ha. Unfortunately for him, it became clear that most of his code was all sound and fury, calculating nothing. Well, that and he took forever to fix bugs because he couldn't really understand it either.
He was soon out on the street, and the rest of the team's policy of just rewriting bits instead of debugging them (it never took very long, and frequently resulted in 1/10 as many lines of code doing twice as much) had soon swept away most of his footprints.
yeah, +1. In this religious war, I side with "if anyone who has a reasonable level of competence with my code can't grasp it at first reach, I have failed in writing it."
Or, famously, "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." --Brian Kernighan
What other technique do you have at your disposal in a code originally written in assembly and then translated to C, and then refactored several times without rewrite?
I personally didn't hear of one that would be usable in this case.
Also, I'm starting to think I should write a script to cut out every comment here that has "code" and "comments" in it - among with several other phrases that signify neverending debates.
I haven't heard the argument about making code deliberately hard to understand either.
I agree that clearer code and/or commenting would have been suitable.
I only latched on to the example because they specifically mentioned that the code wasn't commented. In this case, a few lines of comments might have helped them find what they were looking for. Even if they original programmer was one of those people who just can't stop writing code like:
$a = ($b)?($ab):$c;
d($a);
Maybe some amount of convincing could lead them to leave a comment every once in a while so we can at least get:
// Detect collision
$a = ($b)?($ab):$c;
d($a);
Since it seems like both clear code and comments were absent, either one would have been helpful.
I don't think comments are any kind of substitute for clear, well-structured code. In your example, "Detect collision" still doesn't give me any kind of epiphany about the code. At best, it gives me a slight hint about where to go to get more information. Chances are I'm trying to fix a bug or change the behavior, so I still need to figure what $a, $b, $ab, $c, and d are and what their purpose is.
In other words, I have nothing against good comments, especially on obscure code, but I think they're only marginally useful even in those cases.
Definitely. I wasn't trying to say that they were a substitute. I specifically said both could have worked. In the example they cited, they couldn't even find where to begin. A small comment could have done something about it.
When you can't have both clear code and commenting, you could at least try to do one every once in a while. How can that be a bad thing?
Respectfully, commenting code and making it easily readable don't usually add to the bottom line. So while we all miss playing Pinball, it would be a waste of money to the shareholders.
This game was another casualty of maximizing value towards shareholders and away from all other stakeholders.
I disagree. Sure, in the short term, taking on that technical debt may have made sense, but in the long term, this is a perfect example of how technical debt added significant maintenance costs to a project.
What if dropping Pinball was not an option? The cost to the shareholder would have been much higher than it needed to be.
There's some commonly repeated (and likely even true to some extent) that ~60-70% of the cost of a software system is in maintenance. Which to me, sounds like if you're the contractor providing the system, that means 60-70% of the value is in the maintenance. It does mean taking something of a hit upfront so make things maintainable, but with the right billing structure you can be adding to the profits by Doing It Right as you go. It's certainly still a gamble though; you might not get the maintenance contract. You might be billing hourly and thus don't see any extra cash for your timesavings (and indeed, might see less).
