The Daily WTF: Curious Perversions in Information Technology

2009-02-11 Reply Admin

Code Dependent:
SatanClaus:
Self documenting code is often self documenting
Ya think?
Sounds like a Beatles song: There's nothing you can do that can't be done There's nothing you can sing that can't be sung

great song. Poor WTF. Sure they're obvious, but at least they're present.

Echoing the sentiment about writing comment pseudo-code and then writing code in between. I only do that for complex methods, though. Most of my code runs offa variables

2009-02-11 Reply Admin

SatanClaus:
The sad thing is alot of people think their code is "intuitive" and it is not. I'd rather have to many comments than non at all. Alot of young people thing "it is obvious" what their code is doing. Sorry, you are wrong in many cases. What usually results is a furious effort to find out what variables a, i and z are doing elsewhere in the code.
Self documenting code is often self documenting, but it is simply true that for every 5 SLOC, there should be atleast one comment.

This is a horrible dailyWTF as it is simply an example of what you young (sometimes arrogant) people need to learn how to do in the real world. Just wait 5-10 years for someone to tell you that your code needs updating and when you look at it you don't know what it is doing.

Couldn't have said it better myself. Obvious commenting may seem like a joke, but remembering what you did x number of months/years/projects/drunken-nights-out ago isn't always easy.

2009-02-11 Reply Admin

whoever:
Well, it's better than some of the comments in the xt:Commerce Source:
create_account.php:201: //don't know why, but this happens sometimes and new user becomes admin

Thanx, had a good time searching for "don't know why" in Google Code Search!

http://www.google.com/codesearch?q=don%27t+know+why&hl=en&btnG=Search+Code

or

http://www.google.com/codesearch?hl=en&lr=&q=%22don%27t+know+why%22&sbtn=Search

Aaron · 2009-02-11 Reply Admin

Amazing. I've always gotten a chuckle or two out of the dumb reader replies, but this thread proves that the readership here has finally hit rock bottom.

Irrelevant comments are worse than no comments. They add visual clutter and make it more difficult for someone to internalize the entire method, class, etc.

Unless you're working on something insanely complicated like a new graphics library or an AI, you should never need to write pseudocode. Write stub methods with descriptive names. Stubs are actual code and don't add redundancy. If you have to write pseudocode, it means that your routine either isn't granular enough or doesn't have a clear purpose. FIX IT.

Finally, if you absolutely must write commented-out pseudocode, remove it after the real code is written. I can't believe how many replies just gloss over this, saying "Oh yeah, I right pseudocode and maybe I leave it in there afterwards, so therefore there's nothing wrong with the snippet here" There is absolutely no excuse for this other than sheer laziness. It's sloppy code. Clean it up, FFS.

Emphyrio · 2009-02-11 Reply Admin

Calvin Spealman:
This is no WTF. Some poor comments? Seriously? If you don't have anything worth posting, don't post.

The comments about commenting are an ironic way of pointing out the actual WTF, which is why the author didn't just use

SELECT MessageText FROM Messages WHERE MessageID = ?

2009-02-11 Reply Admin

Aside from the pointlessness and redundancy, another downside to putting in comments like these is that people will read the natural language comments and skip over reading the actual code. Come on, admit it, you did it too. That makes it all the more harmful when the code and comments are out of sync, because you subconsciously assume that you know what is going on from the comments and not actually taking the effort to figure out what the code is actually doing.

2009-02-11 Reply Admin

I saw a real WTF with that code - the selection didn't sort on MessageID so the result could end up being unpredictable.

A true seed for weird messages to the user if there had to be a change in the database.

2009-02-11 Reply Admin

This is how many institutions try to teach people. If you did something wrong with the code, but say what you meant to do in code, you can still get marks for it. Doesn't matter why you wanted to do it.

2009-02-11 Reply Admin

A poor WTF, I have submitted way better stuff than that already.

To the folks that call these comments a WTF: Maybe you should remember that comments should not be about the "why" in most cases, but about the "what", while the code specifies "how" it is done. If your code is so simple that you can tell the "what" and the "why" from the "how", then you may indeed call it self-documenting. If not you should urgently learn these finer conceptual distinctions; it will make you a better programmer. The "what" is the link between specification and code, and it's too often missing. When I see code that doesn't document on this level I sense that the programmer hasn't translated the spec accurately for want of conceptual clarity, and, sadly, too often the quality of the code proves this deficiency.

Conclusion: Tell the maintainer after you what you are doing. The "why" is less important. One day you yourself will be glad about it.

2009-02-11 Reply Admin

Back in the day, I was a maintenance programmer on a military mainframe system. The codebase was 20 years old and the coders had been miltary enlisted and officers, most of whom were neither particularly well trained in programming or particularly excited about the thankless job they were "volunteered" into.

The military has, almost above all else, rules. That goes for a military programming shop. Think about it. How many software quality and process czars in a regular development shop can start a paper-trail than can end up with prison time for the stubborn coder?

Anyways, comments were mandatory. The spirit of this mandate was, of course, "explain why you're doing stuff". The implementation of the mandate was always less high-minded.

Numerous places in the codebase, the work of some clearly disgruntled sergeant in ancient times, had comments to the effect of "This comment is here to satisfy Captain <name>'s requirement to have a comment on each line of code."

2009-02-11 Reply Admin

Personally, I reckon there's at least one more possibility here. The guy writing the code doesn't know what kind of person's going to be maintaining his code - could be a department where there's a lot of annual university sandwich course students or the like. If that's the case, this could be making sure it's bulletproof in terms of making sure that anyone trying to find a problem knows exactly what each line is trying to do.

True, there ought to be more "we've doing this because there're only 7 internal TPS messages" style comments as well, but I can see the point behind the "now we're going to do this" as well. I'm used to assuming that someone looking at my code may well have less grasp of the language than I do.

2009-02-11 Reply Admin

bored:
!WTF.
More comments the better, even if they are "obvious" ones.

this code goes too far. it's almost "i'm trying to teach the language through comments", and completely ignores why i'm writing the code.

by your statement, I should type in chapters (or at least sections) from a learning C# book for every line i type instead of offering a line or two at the top of an important section.

// retrieving data X from db (it may have changed due to events Y or Z) this says what and why because i'll forget in 2 weeks the how is obvious to anyone who can write code

instead of

// look up array for data x // get data x from the db // load into array for data x

this says exactly how, you can figure out the what if you think for a second, but why am i doing it? what's the point? isn't data x already in the array? i'm sure i had a good reason ... or i was tired ... or i was distracted ... hmmm i'll just remove that code. it was obviously a goof.

2009-02-11 Reply Admin

Code Dependent:
Josh:
Of course, as an engineer, I fully expect half the code I've ever written to be posted here by one of my computer science predecessors, though.
Doubtless you meant to say "postdecessors".

Cut him some slack, he's an injunear not a writer.

2009-02-11 Reply Admin

I find lots of code has //TODO: blah in it where it is production ready and tested, but with lots of forward looking comments for future versions.

Just because it's production ready doesn't mean there isn't anything more to do on it, it's just not got the budget, time or client sign off.

I had an manager who insisted i deleted all the TODO comments before i deployed a web app when it was ready. Two months later i was asked where all the new functionality for the next version should be added....

Julia · 2009-02-11 Reply Admin

This sounds like something out of a shop I used to work at. To check a file into source control, you first had to run a home-grown automated code checker. This rigorously enforced a rule governing the proportion of comment lines to source lines. You ended up having to do this simply to fill your quota of comments. (Putting silly comments in pointing out the banality of the system was a good way to get disciplined)

It might have been appropriate in the origins of the company in the sixties, writing really low level stuff, but it was moronic not to change the rules for well-structured object-oriented code.

Rootbeer · 2009-02-11 Reply Admin

"It would be nice to know why the proper range ends in 8, but that's probably documented elsewhere."

If it's not documented here, I doubt it's documented anywhere else, either.

MrsPost · 2009-02-11 Reply Admin

Personally I comment my code for purely selfish reasons. I don't know why I did things the way I did when I go back over it months later. I've worked on too many things between the time I wrote it and the time I need to modify it to remember much of anything.

So I have both functional and observational comments in my code. To save my own sanity.

My rule of thumb when writing comments - write them so that the person who replaced the person who replaced you can understand what's going on. Essentially write for two generations of programmers out. What seems intuitive takes on a whole new meaning with that idea.

Of course, this didn't stop me from commenting a small procedure completely in haiku one day because I was feeling cheeky.

2009-02-11 Reply Admin

//TODO: Remove this comment

2009-02-11 Reply Admin

Tris:
I find lots of code has //TODO: blah in it where it is production ready and tested, but with lots of forward looking comments for future versions.
Just because it's production ready doesn't mean there isn't anything more to do on it, it's just not got the budget, time or client sign off.

I had an manager who insisted i deleted all the TODO comments before i deployed a web app when it was ready. Two months later i was asked where all the new functionality for the next version should be added....

That's when you went into your version control software, rolled back to the baseline with the "TODO" comments and emailed your manager about the change?

2009-02-11 Reply Admin

InsanityCubed:
That's when you went into your version control software, rolled back to the baseline with the "TODO" comments and emailed your manager about the change?

Don't be silly - i laughed in his face and handed my notice in.... :D

Mr B · 2009-02-11 Reply Admin

Tris:
InsanityCubed:
That's when you went into your version control software, rolled back to the baseline with the "TODO" comments and emailed your manager about the change?

Don't be silly - i laughed in his face and handed my notice in.... :D

So you weren't using version control, nor did you make a note of what was left to do when you were told to remove the TODO notes from the code?

I'd have resigned at that point too, in order to cover up my incompetence.

amischiefr · 2009-02-11 Reply Admin

Whoevar:
I often start commenting a method/function/whatever and list the steps that need to be implemented. It may look like this:
public void doWhatIsNeeded {
  // Step 1: connect
  // Step 2: request data X
  // Step 3: for each X do Y
  // Step 4: finish, clean up
}
The code inbetween the comments could even be only one method call. The comments usually stay there. Would this be a bad habit?

No, outlining your steps is a very good habit. I do similar things to lay out the flow before I start coding. If you dont' remove the comments, who the fuck cares? So there are comments OH NOES!!! Too many comments, can't read... People will bitch whether you comment or whether you don't. There is no "right amount" of comments.

dkf · 2009-02-11 Reply Admin

NameNotFoundException:
Conclusion: Tell the maintainer after you what you are doing. The "why" is less important. One day you yourself will be glad about it.

I think I disagree. The "why" is really important (e.g. if you're repeating a query to a database then you really ought to have a good reason to do so) and the "what" is usually clear enough in well-written code. Naturally, if the "what" isn't very clear either then that's an indication that either the code needs refactoring or extensive comments to explain what is going on. An example of the need for the latter is when the code without error checking is pretty simple, with just a few lines of clear calls to other APIs, but once error handling is added it is a horrible mess that just spreads out over page upon page. (Yes, this happens.) When that happens (which is disappointingly often in high-quality code) it's nice to put the pseudocode that you'd write without the error handling at the top in a clear comment before noting that what is below is meant to be the same except for the extra gunk to make it all robust.

Ultimately, a comment in code is there for the next few poor souls who come along tasked with maintaining the code. Remember, that could well be you so write things in the comments that will help you if you were coming to the code cold. And it is ever so important to capture the "why" somewhere, especially for long-term support; if you've got a detailed external requirements capture document somewhere, put a link to it in the code that is detailed enough that you'll be able to look up the rationale in seconds. (Yes, I've been involved in maintaining codebases that were over 20 years old. At that age, "why" is truly critical.)

kastein · 2009-02-11 Reply Admin

whoever:
Well, it's better than some of the comments in the xt:Commerce Source:
create_account.php:201: //don't know why, but this happens sometimes and new user becomes admin

hahahaha, this isn't even a joke! http://www4.ecombase.de/ECOMBASE-XREF/create_account.php.source.html#l215

Addendum (2009-02-11 11:26): EDIT: oh yeah - why I comment my code at work precisely, almost anally: because I have to maintain it. In 3 months, I am not going to remember how it works at all, and a lot of descriptive comments containing both the HOW /and/ the WHY refreshes my mind quite well. The side benefit for my employer is that should I ever leave or be laid off, they aren't left with an unmaintainable mess.

2009-02-11 Reply Admin

Ok, the WTF-ness of recent posts is severely lacking. Get with the program, dudes.

But to the topci at hand -- Yes, having answers for 'Why?' would make better comments.

But it looks like these comments come from what is actually not a bad practice -- writing our some very basic logic and/or pseudocode for your work before writing any actual code. This helps you think through the code before you write, often leading to better code quality. And as you fill in actual code, comments are left that look pretty much like what is displayed in this post.

Is it very helpful commentary? Not really. But neither is it a WTF.

2009-02-11 Reply Admin

Mr B:
So you weren't using version control, nor did you make a note of what was left to do when you were told to remove the TODO notes from the code?
I'd have resigned at that point too, in order to cover up my incompetence.

That's jumping to an inaccurate conclusion. I didn't say anything about source control or documentation. That doesn't mean it wasn't there....

Mr B:
I'd have resigned at that point too, in order to cover up my incompetence.

I'm sorry to hear about your incompetence.

2009-02-11 Reply Admin

rofl:
whoever:
Well, it's better than some of the comments in the xt:Commerce Source:
create_account.php:201: //don't know why, but this happens sometimes and new user becomes admin

Thanx, had a good time searching for "don't know why" in Google Code Search!

http://www.google.com/codesearch?q=don%27t+know+why&hl=en&btnG=Search+Code

or

http://www.google.com/codesearch?hl=en&lr=&q=%22don%27t+know+why%22&sbtn=Search

Even better yet, 60 references to "thedailywtf"

2009-02-11 Reply Admin

I'm deeply worried by the number of posters here who defend this commenting style. Unless you're trying to teach someone language syntax, there's never an excuse for this style of commenting; it simply repeats what's already crystal clear from the code itself if you've written it properly. The code in the article says nothing about the purpose of the code; it's just a stream of consciousness from the developer about the steps they're taking to accomplish this unspecified goal. How is this useful to anyone? If you're coming in to maintain the code later, it doesn't give you any clues about the developer's rationale.

Well-chosen variable and function names and well-thought-out control flow can make comments almost completely unnecessary. Any information that's relevant to the code and can't be made apparent by the code itself still needs to go in a well-written comment that gives the reader all the necessary background they need to fully understand why the code was written as it was; however, any comments that don't fit into this category are clutter and significantly reduce readability.

Maintainability is obviously a concern, but it seems to be often misunderstood what information is most useful to future maintainers (including yourself). I don't need an inline language syntax reference; I need readable, easy-to-understand, straightforward code. The only inline comments that are generally necessary fall into these three categories:

Details about any gotchas that the developers have run into and written code to work around. Example: // TRICKY: Despite what its documentation says, this API returns a 1-based index, so we must decrement its return value by 1 to get the correct index
Hacks (if any) and what the code should more ideally be doing. Example: // HACK: These hardcoded values should live in a configuration file
Things that still need to be done. Example: // TODO: Handle possible error condition if file is not found

API documentation is also important, but is arguably outside the scope of "comments".

2009-02-11 Reply Admin

NH:
I saw a real WTF with that code - the selection didn't sort on MessageID so the result could end up being unpredictable.

not only that, but since the code only seems to be using 1 of the messages, why does it need to retrieve all 7 from the database? Seems like a waste to me. Probably should be using a stored procedure too instead of building dynamic SQL in the program.

2009-02-11 Reply Admin

OK, the real WTF (I hate to use that hackneyed phrase, but feel I must) is that the article emphasizes the comments as the WTF. Every one of us has seen comments like this. Most of us have written comments like this, probably because we were TOLD to by a teacher or supervisor or some such at some point in our education and/or careers. Sure, such comments are useless, but hopefully most of us came to terms with that a long time ago.

What is really f**ed up about this code is what is described underneath it in the article...the fact that it takes an ID, checks if it is in a range, loads all ID's in that range from the database, then uses the original ID to look up the value it wants from an array. Why on earth not replace all of this with one query using the passed in ID?

2009-02-11 Reply Admin

Aaron:
Amazing. I've always gotten a chuckle or two out of the dumb reader replies, but this thread proves that the readership here has finally hit rock bottom.
Irrelevant comments are worse than no comments. They add visual clutter and make it more difficult for someone to internalize the entire method, class, etc.

Unless you're working on something insanely complicated like a new graphics library or an AI, you should never need to write pseudocode. Write stub methods with descriptive names. Stubs are actual code and don't add redundancy. If you have to write pseudocode, it means that your routine either isn't granular enough or doesn't have a clear purpose. FIX IT.

Finally, if you absolutely must write commented-out pseudocode, remove it after the real code is written. I can't believe how many replies just gloss over this, saying "Oh yeah, I right pseudocode and maybe I leave it in there afterwards, so therefore there's nothing wrong with the snippet here" There is absolutely no excuse for this other than sheer laziness. It's sloppy code. Clean it up, FFS.

Absolutely. One of the guys that I work with has a nasty habit of not only writing really ugly code, but also sprinkling stupid, superfluous comments like this throughout his ugly (often hackish) code.

I often have to go through and clean up the code (because it doesn't work right) and I just end up completely removing comments like this.

The worst part is that he will sometimes go through my code and put stupid comments like this. I can only assume it's because he can't remember what certain language constructs do and he has to have psuedo-code to understand it.

Often the comments are mostly inaccurate. Usually, it's because he wrote the comment before the code or because he copied and pasted something he wrote earlier. This kind of shit drives me crazy, because I actually take the time to write out nice block comments explaining WHY I am doing what I'm doing, and he just write stupid bullshit.

Examples: // get the selected items var m = gridPanel.getSelections();

// have to convert any new lines into
$comments = str_replace("\n", '\n',$row['comments']);

// clear out the previous tab_items $tab_items = "";

// clean the properties value to send to the function $ids = pgArrayTrim($record['industries']);

// enable the contact and event tabs sub_tabs.getItem('event_tab').setDisabled(false); sub_tabs.getItem('contact_tab').setDisabled(false);

// reload the accounts combo so that the new account // will be in the list dscomboaccounts.load();

WTF

davidyorke · 2009-02-11 Reply Admin

Code Dependent:
Josh:
Of course, as an engineer, I fully expect half the code I've ever written to be posted here by one of my computer science predecessors, though.
Doubtless you meant to say "postdecessors".

What he needs is to build a Successor Naming Machine!

2009-02-11 Reply Admin

Code Dependent:
Josh:
Of course, as an engineer, I fully expect half the code I've ever written to be posted here by one of my computer science predecessors, though.
Doubtless you meant to say "postdecessors".

Otherwise known as successors.

2009-02-11 Reply Admin

I can't believe none of you have figured out the right answer yet. So let's work it through nice and slow:

Who demands comments? Managers.
Who enforces this demand? Managers.
How do they enforce it? They spot-check your code.
What do they see? Scary gibberish and comments.

So, since the managers can't read the code, the comments are there to provide an English translation. Thus it makes perfect sense to:

// declare a new variable
int i;
// assign it an initial value
i = 3;

Code Dependent · 2009-02-11 Reply Admin

J:
Code Dependent:
Doubtless you meant to say "postdecessors".
Otherwise known as successors.

Okay, you array of posters all saying the same thing about "successors": that is mere pedantry. "Postdecessors" is humor. I was hoping I wouldn't have to point this out, but... (sigh).

2009-02-11 Reply Admin

Kanitatlan:
END //procedure SET_ACTIVE_FLAG

This one makes sense.

The real WTF though is that there's probably an insane policy in place that requires a comment on every line, no exceptions, even when it's nonsensical to do so.

Voodoo Coder · 2009-02-11 Reply Admin

General Failure:
I can't believe none of you have figured out the right answer yet. So let's work it through nice and slow:

Who demands comments? Managers.

Who enforces this demand? Managers.

How do they enforce it? They spot-check your code.

What do they see? Scary gibberish and comments.

So, since the managers can't read the code, the comments are there to provide an English translation. Thus it makes perfect sense to:
// declare a new variable
int i;
// assign it an initial value
i = 3;

You have some strange managers...

What the heck kind of manager would want to review code if they couldn't read it? What EXACTLY would they be looking for?

Seriously. Please tell me you are trolling.

Charles400 · 2009-02-11 Reply Admin

System.out.println("Comments? Who uses comments?");

2009-02-11 Reply Admin

Whoevar:
I often start commenting a method/function/whatever and list the steps that need to be implemented. It may look like this:
public void doWhatIsNeeded {
  // Step 1: connect
  // Step 2: request data X
  // Step 3: for each X do Y
  // Step 4: finish, clean up
}
The code inbetween the comments could even be only one method call. The comments usually stay there. Would this be a bad habit?

Yes

2009-02-11 Reply Admin

I once worked on a program that was filled with comments like:

// Add brdamt to crlamt giving totamt
totamt=brdamt+crlamt;

I suppose for people who can't remember what "=" and "+" mean, this may have been a useful comment. But as such a person is unlikely to be able to make any sense of the program anyway, the comment was useless. Something more helpful would have been an explanation of what "brdamt" and "crlamt" are. Some sort of amounts, I guess, but what is a "brd" or a "crl"?

I'm amazed at all the posts asserting that useless comments are harmless. As someone earlier replied, they add clutter, which wastes the time of the reader trying to figure out the program. Okay, one useless comment in a 3000 line program would do little harm, but at what point will you concede that useless comments are wasting the maintainer's time? What if there are ten pages of useless comments for every line of code? Surely in that case you would concede that I will waste a lot of time scanning through useless comments trying to find the meaningful comments or the code itself. Well, if there's just one useless comment for each useful comment or line of code, then fully 50% of my reading time is wasted. I've had plenty of tasks where I had to fix a bug or make a minor change that required just a couple of lines of code, but I've had to spend 8 hours searching through the code to find the place to make a change and then 10 minutes actually making the change. If half that reading time was wasted, then my productivity could be practically doubled by eliminating the worthless comments.

2009-02-11 Reply Admin

Whoevar:
I often start commenting a method/function/whatever and list the steps that need to be implemented. It may look like this:
public void doWhatIsNeeded {
  // Step 1: connect
  // Step 2: request data X
  // Step 3: for each X do Y
  // Step 4: finish, clean up
}
The code inbetween the comments could even be only one method call. The comments usually stay there. Would this be a bad habit?

No, I do the same thing - use comments to delineate sections of a large (50-60 line) method. It's handy to be able to call out the large scale logic.

2009-02-11 Reply Admin

"Unless you're working on something insanely complicated like a new graphics library or an AI, you should never need to write pseudocode."

You sir are the real idiot.

2009-02-11 Reply Admin

adiener:
I'm deeply worried by the number of posters here who defend this commenting style. Unless you're trying to teach someone language syntax, there's never an excuse for this style of commenting; it simply repeats what's already crystal clear from the code itself if you've written it properly. The code in the article says nothing about the purpose of the code; it's just a stream of consciousness from the developer about the steps they're taking to accomplish this unspecified goal. How is this useful to anyone? If you're coming in to maintain the code later, it doesn't give you any clues about the developer's rationale.
Well-chosen variable and function names and well-thought-out control flow can make comments almost completely unnecessary. Any information that's relevant to the code and can't be made apparent by the code itself still needs to go in a well-written comment that gives the reader all the necessary background they need to fully understand why the code was written as it was; however, any comments that don't fit into this category are clutter and significantly reduce readability.

Maintainability is obviously a concern, but it seems to be often misunderstood what information is most useful to future maintainers (including yourself). I don't need an inline language syntax reference; I need readable, easy-to-understand, straightforward code. The only inline comments that are generally necessary fall into these three categories:

Details about any gotchas that the developers have run into and written code to work around. Example: // TRICKY: Despite what its documentation says, this API returns a 1-based index, so we must decrement its return value by 1 to get the correct index

Hacks (if any) and what the code should more ideally be doing. Example: // HACK: These hardcoded values should live in a configuration file

Things that still need to be done. Example: // TODO: Handle possible error condition if file is not found

API documentation is also important, but is arguably outside the scope of "comments".

This WTF and argument back and forth is ridiculous. You know what, everybody has different coding styles and ways of doing things. Who's to say one person's particular style or preference is better than another. Arguing over personal preferences is pointless. Some people like comments (no matter how superfluous they might seem to others) and some people don't. Its like arguing over what kind of writing utensil that someone uses to take notes and arguing that anyone who uses a pen instead of a pencil is wrong. Anybody who's been coding for any period of time knows there may be many different ways to accomplish the same task. Frankly, if the code does what it's supposed to do in a quality manner, who gives a rats a$$ if ten people have ten different ideas of how much and what kind of comments should be in the code.

2009-02-11 Reply Admin

lanmind:
Same here. I often write a bunch of comments - like placeholders - to get the flow and then go back and add the code. I may or may not remove the comments afterwards.

I know what you mean. I often jack up my car to change the oil. I may or may not remove the jack when I'm done.

After all, if it was useful to have it there when I was changing the oil, how can it hurt to leave it there after the oil is changed?

2009-02-11 Reply Admin

adiener:
- Details about any gotchas that the developers have run into and written code to work around. Example: // TRICKY: Despite what its documentation says, this API returns a 1-based index, so we must decrement its return value by 1 to get the correct index

And don't forget to mention the faulty API version so the comment and workaround don't linger in the code until you're using API version 8.3 when it was really only a problem with version 1.1!

2009-02-11 Reply Admin

Anonymous:
Indeed, this is a common one. Some people just have to document self-documenting code.
// If the object is null throw a new NullReferenceException if (object is null) throw new NullReferenceException();

Why? Why would anyone explicitly create a NullReferenceException()? Any code that dereferences a null pointer has a programmer's error. Fix the code!

2009-02-11 Reply Admin

Voodoo Coder:
General Failure:
I can't believe none of you have figured out the right answer yet. So let's work it through nice and slow:

Who demands comments? Managers.

Who enforces this demand? Managers.

How do they enforce it? They spot-check your code.

What do they see? Scary gibberish and comments.

So, since the managers can't read the code, the comments are there to provide an English translation. Thus it makes perfect sense to:
// declare a new variable
int i;
// assign it an initial value
i = 3;
You have some strange managers...
What the heck kind of manager would want to review code if they couldn't read it? What EXACTLY would they be looking for?

Comments. It's called compliance. Obey.

2009-02-11 Reply Admin

nd:
This WTF and argument back and forth is ridiculous. You know what, everybody has different coding styles and ways of doing things. Who's to say one person's particular style or preference is better than another. Arguing over personal preferences is pointless. Some people like comments (no matter how superfluous they might seem to others) and some people don't. Its like arguing over what kind of writing utensil that someone uses to take notes and arguing that anyone who uses a pen instead of a pencil is wrong. Anybody who's been coding for any period of time knows there may be many different ways to accomplish the same task. Frankly, if the code does what it's supposed to do in a quality manner, who gives a rats a$$ if ten people have ten different ideas of how much and what kind of comments should be in the code.

This isn't about personal preference, it's about software quality and ease of maintenance. Those things are objectively measurable (assuming a reasonable working definition of "quality"). Trivializing it as if it's personal preference only buries the problem deeper and perpetuates an attitude of indifference toward something with real detrimental impact. Yes, in the strictest of terms, comments have no direct effect on the quality of software after it's compiled, but their indirect effect is only one step removed from it. The philosophy of "if it does what it's supposed to when it compiles, it's good code" really isn't applicable in many situations these days.

2009-02-11 Reply Admin

Because they never learned why they should comment their code.

The Professor said you must comment your code so they started doing stuff like this:

i++; // increment loop variable by one

As I've made my transistion from the classroom to a real world programmer I think most problems can stem from how we were taught.

In the classroom I receive an assignment, I code it and turn it in. The only person who will ever read the source, other than me, is the Professor. The only one who will ever have to maintain it is me(and usually these are 'one-offs' which even I will never look at again).

How do you teach CS concepts like that? If no one is ever going to have to maintain it why document it? If no one besides you is ever go to touch it why worry about encapsulation, source control, etc?

What they should do is this: Have everyone code a project and turn it in. Then pass the projects back out to other people. Now everyone has to add a feature to someone else's project. Suddenly all these CS concepts become clear. You don't really comprehend why you need to document your code (and how to do it well) until you've struggled to understand somebody elses undocumented code. You don't understand the principle of orthogonality until you've had to work with someones code that has lots of unexpected dependencies etc...

2009-02-11 Reply Admin

mh:
Kanitatlan:
END //procedure SET_ACTIVE_FLAG
This one makes sense.
The real WTF though is that there's probably an insane policy in place that requires a comment on every line, no exceptions, even when it's nonsensical to do so.

I have to agree that I like ending functions/subroutines etc with 'end;// function functionName' If you have either long functions or subroutines that cross more than one screen, it's easy to scroll past the end/start and jump into the next function. Sometimes it's easy to tell you did it, sometimes it's not, but putting the function name at the end of the function certainly makes it clear when you've managed to skip from one to the other.

On the other hand, I've seen too many bits of scripting where the psuedo-code and the code had very little in common.

The How, Not the Why

Leave a comment on “The How, Not the Why”