programming and human factors
by Jeff Atwood
Today's rumination is not for the weak of heart. It's from the venerable C2 Wiki page Code For The Maintainer:
Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.
Perhaps a little over the top, but maybe that shock to the system is what we need to get this important point across to our fellow developers.
If scare tactics don't work, hopefully you can develop a grudging respect for the noble art of maintenance programming over time. It may not be glamorous, but it's 99% of the coding work in this world.
In my experience, besides sensible comments, sensible naming conventions for packages, classes, methods, etc., sensible project layout and code formatting are paramount to achieve code maintainability. All this, of course, must be agreed upon by the team. Now, the problem problably is to find an agreement on the meaning of 'sensible' :)
My rumination on this is "Code should be written for humans, the machine can always be made to read it." In maintaining code, the compiler can read any crud and make enough sense of it to 'work'. The true issue is if a human can look at a page and instantlly know what's going on. For example seeing a case or casscading if then in a simple clean block "Oh, that's were the action is determined. The new one goes in here."
My worst face in the desk was a Russian "Don't question it works." He goto'd in and out of a called procedure that called the procedure again on one of the excursions out on a goto. I disassembled the machine code just to figure out why it ever worked at all. (No stack overflows, access violations etc it ran thousands of transactions.)
AL Pareigis on June 21, 2008 12:56 PMJeff,
I believe that Comments are important as much as the code that works(Hoping that Codes do work ALWAYS)...But sometimes overcommenting can also be a disaster..I hope you guys have never came accross nething of such kind..But i hve...
i hve a few 1000 lines of codes which is 50% Code and 50% Comment...Ever Imagine, how difficult it wud be to read the codes when there are comments for every line of Code?
Its worst then hving no Comments...Trust me on this...i hve Gone through this.
Ruvi on June 22, 2008 11:13 AMI read tour tweet but don't think you're gonna do a blog post too.
By the way nice picture :)
kmilo on June 23, 2008 2:53 AMIt is a great photo! Project managers can use it for programmers who are too lazy)
Else on June 23, 2008 8:38 AMI like this article so much that I took the "always code as if..." part, put it together in a document along with a picture of Gollum from the Lord of the Rings trilogy, and posted on the wall outside my cube.
VegeBrain on June 23, 2008 10:11 AMWe are the borg...
Refactoring is inevitable'.
You will be frustrated...
netflix queue emptys
sadly, the chick flick arrives
the ghoul still unknown
Documenting code is important. But the big problem with documented code other than the inevitable change not being updated in the docs is that it doesn't document the protocol for using it. I consistantly see functions that are part of a larger chain of events with no consistant clues regarding when and how they are to be used. I'm a big fan of software that has been designed and that design documented. I've left a fair amount of it behind me, but have almost never seen it going into a project.
As far as writing code goes I prefer clarity over everything. On most modern systems the tricks I know to make code run faster just aren't as necessary as they were back when I wrote my helloworld. I've been writing code since 1974. Back then you needed all of the tricks to fit into memory and make things work fast. Much of that is now just academic farting around. My pet peeves involve programmers who depend on things like operator order of precidence for their code to work correctly.
The first big thing I wrote was a twisty maze of stateful code with lots of goto statements. It worked, but the first maintenance cycle required a complete rewrite because _I_ couldn't figure out what I had done. We do get better over time...
I can't believe (If I'm wrong forgive me, I tried to read all comments first) That no one else has picked up on possibly the best comment on a blog ever
Andy Wong you are awesome.
Everybody please read the second comment to this entry.
Then read it again.
It is absolutely the best
Red on August 16, 2008 6:48 AMI have felt the pain as well but,
I began my career as purist and nearly threw in the towel from endless arguments. The bottom line is our work costs money, and cost results in pressure from management, which will always result in shortcuts being taken - ALWAYS - so going on about it will only result in destroying relationships with the people who can advance your career and renumeration.
Also fixing annoying code takes longer - so more money - most people want pay you twice as much to do it right the first time, but will hardly bat an eyelid forking the money out for maintenance. Poor code is a cash cow - dont mess with it :)
Always remember were in it for the money (enjoying solving its puzzles is a just a bonus) and that pride goeth before the fall.
IsItReady on October 1, 2008 10:05 AMghdsfgh hgf hsgf fgsdh f g
hftydhgfdhd hfd hfd on June 8, 2009 9:19 AMThere's only one thing worse than no comments. And that's comments that are WRONG. I inherited code where the guy started out meaning well, but then when he got in a hurry would copy code, change it, but leave the comments alone.
Benton Jackson on February 6, 2010 10:38 PMI actually found these comments in some c code I had to look at a while ago.
C is not my usual language of choice but knowing it does come in handy every once in a while ;)
The comments were all written by the same developer who was actually quite good but sometimes he had a bad case of sense of humour failure.
/*I don't know what the f*** this is supposed to do*/
And
/* Some months later..........
* I commented the code, and guess what, it didn't help :) */
And sometimes he would get quite frustrated
/* F***, F***, F***, F*** */
and
/* F*** me backwards.......
* This is such a lot of effort just for some lazy ass in Customer name withheld from post for obvious reasons. *sigh*
* I REALLY don't get paid enough for this :( */
I agree with Charlie Lobo that everything has its use, including GOTOs. Not that I use them often (once in the past year and a half), but I would argue that my use *improved* the quality and readability of the code I was writing.
I was working on a C routine to set up a serial port for later communication (open it, set the baud rate, parity, ...). Since there are so many API calls in that, and each one has the possibility for failure, I simply have all failed calls GOTO a failure label that cleans up (closes the port and returns a bad value).
The other options (in order of readability) would have been:
- call another function to do the cleanup and then return a bad value each time
- same cleanup in each place
- write a macro that does the cleanup and call it each time
I would argue that since the failure cleanup code was in a logical place (at the end of the function) and it was the only use of GOTOs (I wasn't trying to use them for looping or anything where better constructs already exist), that I made the best choice available.
That said, legitimate uses for GOTO are extremely rare and should always be well thought out (how else would I remember what I used it for and when I used it?).
Jon on February 6, 2010 10:38 PMI am interested to know which company would hire a programmer who looks like that.
Aaron Seet on February 6, 2010 10:38 PMJeff-
How did you get a picture or our co-worker?
By the look of many code bases out there, there's probably several people that are one or to "gotos" away from turning into this guy.
Most places are get it out now, worry about it later. That combined with employee turnover and offshoring leads to some pretty cryptic situations.
I always hum "On top of Spaghetti, all covered with bugs, I lost my poor data, it all covered with crud..." to myself to keep my sanity while debugging through the lines of someone else's craptacular code.
Getting up and going for a walk always helps out as well.
The comments to this entry are closed.
Subscribe in a reader
Subscribe via email
|
|
Traffic Stats |