Regarding what was said by secretGeek I must definitively agree with that. It happens always to me too and I do the same things that he does.
On the other hand I usually only comment the ‘dark’ operations that are in my code because I try to code in a way that comments are not needed.
Something like
For rowIndex:=0 To dataTable.Row.GetUpperBound(0)
datatable.Rows[rowIndex].Column(“money”) = currentMoney
Next
Doesn’t needs much comments because its selfexplanatory.
Some great advice! Love the image, what is it from?
I must admit that I’ve been through the “Who wrote this sh*t??” process, only to find that SCC tells me “You did. But quite a long time ago”.
Rather than beating myself up, it gives me the opportunity to see how my coding has changed (and, hopefully improved).
My favorite ever was when I had to re-write a legacy application that was written by a guy who had long moved into management.
I was totally lost as to what some items were supposed to be doing and I came across some really oddly named variables, so I started there and went upstairs to ask some questions.
Me: "Hey, what does the var coffeeCup do and where did that come from?"
Him: “Oh I can’t remember that. But I did go through a period where I titled variables after THINGS I SAW ON MY DESK AT A GIVEN TIME.”
Le sigh.
I write crap code at times. I’ll admit that. But at least I understand why.
Whenever I come up with a conceptually simple, elegant algorithm for solving a problem, I think of it executing visually, as though its a mechanical device chugging away. But, as they say, a picture is worth a thousand words. What seems so simple as an image/animation can be extremely difficult to describe in code (or in English, for that matter). This difficulty is what causes very poor-quality code to be written.
The only problem now… what do I have to do to overcome such obstacles?
I think a large portion of it is office politics.
You only have two weeks to write the program, but you can maintain it for years and that’s ok.
I’m not so sure that simply commenting code solves the whole problem, and formal UML diagrams can sometimes be confusing in themselves.
I’ve introduced the concept of writing a brief technical overview for each feature or module that each person implements; these normally contain UML diagrams but at the same time a description to go along with this helps a lot.
Each project has a wiki where we store these documents.
The problem, as always, is when you have the opportunity cost of Developing a New Feature versus Documenting an Existing Feature.
One of the things I find desperately sad is the number of people who believe these issues are about “style”, “fussiness” and “cost-effectiveness”.
When I tell someone code needs to be rewritten, it is not because it looks a mess or is confusing or I don’t like the style: it IS a mess.
And I define mess as “it can be logically demonstrated that no matter what you do to it, it will never work, only appear to do so.”
Take this, for example, as not altogether atypical “acceptable” and “cost-effective” coding where a rewrite is considered “offencive”, “time-wasting” or “perfectionism” by management and certain members of the team…
–
MyFunction(Parameters…)
'Bug fix added by programmer when she realises her code isn’t working (this is within the same function, not elsewhere in the project)…
If MyFunction() = SomeAberrantValueObtainedDuringTesting Then
MyFunction() = HardcodedGuessedCorrectValue
End If
If MyFunction() = SomeOtherAberrantValueObtainedDuringTesting Then
MyFunction() = HardcodedGuessedCorrectValue
End If
etc…
End MyFunction()
–
This example is greatly simplified: there were a few spurious recursions in the percentage calculation and the If-Then statements which performed the hard coded corrections were deeply entangled within many self-contradictory layers and spurious recursions.
The errant belief that a function can be used as a variable to hold its own return value while being calculated through many partial steps was the least of this programmer’s problems. Yet, this was accepted by management because it “appeared to work” when tested.
Add to this that such people are regarded as model employees while the rest of us are “troublemakers” and “less employable”, it is a wonder that more of us don’t become psychotic…
BTW, it took 2-3 lines of code to replace that huge function with code that worked.
runs away scared
That is, from both horrorshow and the poor coding!
That’s in the first chapter of Perl Best Practices by Damien Conway.
I think it might’ve replaced ‘violent psychopath’ with ‘axe murderer’, but the sentiment is the same.
It takes time to learn to write excellent code, so to me it seems that writing bad code is the forgiveable mistake of inexperienced programmers. But learning to document your code should be the first thing you learn in CSC 100 course.
After major reductions in workforce in our organization, I’ve inherited the code of several other (much younger) developers. I am willing to put up with spaghetti logic if I have to, but there is no excuse for not commenting or using meaningful identifiers!
I have found several mistakes in their code which they probably would have caught themselves had they taken time to document!
Good thing I don’t know where they live. 
Merely adding comments rarely helps and they often become lies when code is updated but comments are not. A better methodology would be to refactor the code such that you can read what it is doing and not need comments. By which I mean variable names that are longer and descriptive and breaking functions down into sub functions that do exactly a single thing and renaming it to represent that single thing. (Single Responsibility Principle)
I’m on my second programming job now and both places have told me NOT to comment the code. They say it’s a brittle association that just ends up making things worse because no one updates the comments when they update the code.
It’s certainly true about the failure to update the comments, but what’s the correct path? The first job was getting on the unit test bandwagon and the champion of that push claimed that the tests document the code. I didn’t get much out of the stuff he had already done though.
Anyway, that’s what I’ve seen so far in my brief career.
this is especially true for me as i maintain my own code, am a raving psychopath and know where i live.
i need to watch out for myself. 
@Jon on June 19, 2008 08:48 AM
"each one has the possibility for failure, I simply have all failed calls GOTO a failure label that cleans up"
Sounds like the C equivalent of local exception handling, so probably quite a reasonable approach.
Two alternative approaches I’ve seen for that situation:
status_ok = apifunction1();
if (status_ok)
nbsp;nbsp;status_ok = apifunction2();
if (status_ok)
nbsp;nbsp;status_ok = apifunction3();
…
if (!status_ok)
nbsp;nbsp;cleanup();
Or even simpler using short-circuit evaluation:
status_ok = apifunction1();
status_ok = status_ok amp;amp; apifunction2();
status_ok = status_ok amp;amp; apifunction3();
…
if (!status_ok)
nbsp;nbsp;cleanup();
Both seem just as clean and don’t use the “dreaded GOTO”.
One of the ironies of life is that our Indians (mostly 20-somethings) are sent off to “maintain” 30 year old COBOL code so that Our Employer (a Fortune X00 company) can keep all those other Fortune X00 clients locked in. What goes around comes around. The Cream of IIT learning the stinky habits of dead white guys. And this is truly cruddy code. I suspect that much of the touted Indian Uber Menchen are doing just that.
And this is the evil side of “accepting” being a maintenance programmer: one gets assimilated into shit. After a while, if you’ve got the spouse, and the kids’ braces, and the vacations, etc.; meh, it’s a living. THAT’s where truly evil code comes from.
I must be lucky - I have really bad short-term memory, so even from my earliest days in college I always wrote my code (and comments) so that I could come back and figure out what I was doing - because the chances were that in a few days I’d have forgotten!
I think that should be a required thing in college programming classes - give an assignment, have the students program it, and then archive it until the end of the semester and give it back to the students and have them maintain it (make changes, or something). That’ll give them some appreciation for good commenting practices!!
ilcavero,
“Always code as if the person who ends up maintaining your code is going to be yourself, because at first it will always be”
That’s wrong, and Jeff is right.
People will build for themselves in exactly the way they like things. They’ll use technologies or methods that none of the rest of the team use, and they’ll be just fine with that.
And everything will be fine until they go on holiday and the system falls over and someone with little experience has to fix their code.
If you at least learn and can see you own mistakes later on must be a good sign, a sign that the brain still function and that there is a progress One shouldn’t expect everyone to write “perfect” code from start. What one think is perfect today can seem pretty bad after a while. But, there are people that do not improve over time, they should be doing something else I think…don’t imagine they even read codinghorror.