CodeThatDocumentsItselfSoWellItDoesNotNeedComments

http://thedailywtf.com/Articles/CodeThatDocumentsItselfSoWellItDoesNotNeedComments.aspx

by edw519 • 17 years ago

41 39 17 years ago

thedailywtf.com

83457• 17 years ago

Great idea for an April Fools Day prank

pmichaud• 17 years ago

I would rather support that, than most of the code I've actually been asked to support.

andrewljohnson• 17 years ago

Here here.

EDIT: Hear, hear.

hughprime3• 17 years ago

a) http://en.wikipedia.org/wiki/Hear,_hear

b) The little triangular "upmod" button is perfectly sufficient to express your agreement if you don't have anything else to add.

rapind2• 17 years ago

Is it really all that difficult to throw in a comment explaining what it is you're trying to do when it's not obvious to someone other than yourself?

hughprime3• 17 years ago

Eliminating _all_ comments is a little extreme, but if faced with the choice between excessively long names and insufficiently descriptive names, I'll go with excessively long every time.

I've spent way too many months digging around in Fortran code where every variable and function name was less than eight characters (actually the eight-character limit has been gone since Fortran 77, but some people still insist on writing Fortran 90 as if it were Fortran 4).

kscaldef• 17 years ago

It appears to me that it's synchronizing inventory change records between a store front and the physical warehouse. I could be wrong, but I imagine it's something pretty similar to that. And, as much as I do shudder at this code, the names did give me a pretty good idea of the intent.

tetha2• 17 years ago

This is however a major problem I have with comments: If it is obvious to me, my mind never ever spends a conscious second thinking about this. For me, the problem does not exist at all. So, tell me, how am I supposed to comment something which might be not obvious to someone else if I don't know it is there?

joe_the_user2• 17 years ago

I bet the real code had all the other problems of real code PLUS the absurdly long names.... At that rate, I'd worry about carpal tunnel syndrome.

tetha2• 17 years ago

some letters + (In eclipse) Ctrl+Space, (in Vim) <C-p> or <C-n> in insert mode beat CTS with long names.

mildweed• 17 years ago

This example is only really annoying because the items were almost full sentences. I prefer small 2-3 word functions.

But really, like pmichaud said, I'd rather support this than, say, reverse engineer Google Analytics code http://www.google-analytics.com/ga.js

NathanKP3• 17 years ago

Obviously the Google Analytics people didn't actually write that terrible mess. They used code compression software to obfuscate it and reduce its size.

But seriously, two to three word functions and variables aren't bad. Technically though C++ variables have a max size of 255 characters. At least that is what I seem to remember. Am I right?

petewarden• 17 years ago

I'll come out of the closet and admit that I like descriptive names. There's a point they get ludicrous, but that's also a very clear sign the concept they're representing has become confusing and unwieldy too. If you can't come up with a name that's both clear and short, maybe the function's purpose is also unclear.

After many years of maintaining large codebases written by other people, the comments are very seldom useful, and often actively misleading, thanks to code changes over time. Coders seem a lot more reluctant to change a function so it no longer does what the name implies than they are to modify code without updating the comments.

rapind2• 17 years ago

I'm with you all the way on descriptive names.

As for comments though, in my experience they can be extremely useful. And I don't mean just one liner's but a couple sentences here and there explaining what you're doing and why you're doing it.

Agree with you also though, that often a coder working with someone else's base won't take the time to do it. I think this is because we naturally take less pride in maintenance work then we do in the creation of an application.

abstractbill• 17 years ago

The only comments I ever find useful are the "unprofessional" ones - things like "WTF, FooCorp are complete dicks and didn't implement the Blah spec properly, so now we have to work around their shit here". Without those kinds of comments it can be hard to understand the motivation behind broken-looking code that is actually broken by necessity.

ilyak• 17 years ago

Pictures of adorable kittens on my news.yc.

NathanKP3• 17 years ago

Umm... spam? I don't get it.

raganwald• 17 years ago

Quite possibly an arch way of saying that DailyWTF postings are a little lowbrow for HN?

edw5192• 17 years ago

Papa Bear:

  for(i=ii;i<iii;i++){
    for(j=jj;j<jjj;j++){
      for(k=kk;k<kkk;k++){
        doSomething();
      }
    }
  }

Mama Bear:

  for(YearCounter=FirstYearOfCycle;YearCounter<LastYearOfCycle;YearCounter++){
    for(MonthCounter=FirstMonthOfYear;MonthCounter<LastMonthOfYear;MonthCounter++){
      for(DayCounter=FirstDayOfMonth;DayCounter<LastDayOfMonth;DayCounter++){
        doSomething();
      }
    }
  }

Baby Bear:

  for(Year=FromYear;Year<ThruYear;Year++){
    for(Month=FromMonth;Month<ThruMonth;Month++){
      for(Day=FromDay;Day<ThruDay;Day++){
        doSomething();
      }
    }
  }

mkyc2• 17 years ago

The moral of the story is not to use shorter names, but to write better code.

  Date start = ;
  Date end = ;
  Iterator i = new DayIterator(start, end);
  while (i.hasNext()) {
    doSomething(i.next());
  }

Your Papa Bear example iterates over a cube in a 3d array. Your Mama Bear example is some seriously broken date iteration code (so you change lastDay from within doSomething?). The Baby Bear is equally broken 'time period' iteration code.

Writing self documenting code isn't about giving everything complete and proper names. It's about choosing comprehensible and trackable names. You introduce Mr. Joseph Harrison as such, but you may thereafter call him Joe.

  BufferedInputStream bufferedInputStream = ... // bad, too formal
  BufferedInputStream bis = ... // bad, too casual
  BufferedInputStream stream = ... // ok
  BufferedInputStream input = ... // good

The Baby Bear code's naming is a bit off too. Is it inclusive or exclusive? I would not be bothered if I saw:

  for (y=firstY; y<=lastY; y++) {

The letter 'y' is obvious (yy/mm/dd), and its scope is small.

edw5192• 17 years ago

The moral of the story is not to use shorter names, but to write better code.

The scope of the post was variable naming. I used dates and "The Three Bears" for a light example of variable naming that almost anyone could understand. I did not even begin to address "better code". I'll save that for another (or hundreds of other) posts.

Your Mama Bear example is some seriously broken date iteration code (so you change lastDay from within doSomething?).

The code is fine. It only becomes "seriously broken" if you change the loop variable within the iteration, in which case you seriously broke it with poor practice.

The Baby Bear code's naming is a bit off too. Is it inclusive or exclusive?

The naming is fine. So is the code. Your question of inclusivity or exclusivity is meaningless without understanding the assignment of the iteration variables, which again, was outside the scope of the post.

The letter 'y' is obvious

No it's not obvious. That's the whole point. It's extremely poor practice (See Papa Bear example.) You cannot assume the poor sucker who maintains your code will know what "y" means. And Heaven help him if he tries to do a global search for that variable in 2,000 lines of code. Which may lead him to reuse it inside the iteration. Which is just about the only way to "seriously break" it as in your Mama Bear complaint.

Your revisions will cause exactly the problem I was demonstrating to avoid.

mr_dbr• 17 years ago

They should just switch to Objective-C/Cocoa and that code would be perfectly normal!

gruseom• 17 years ago

Though the names are long, I don't think the naming style is all that bad. The real problem with this code is its non-orthogonal logic. It has duplication and crossed wires all over the place.

DannoHung2• 17 years ago

Well, you can tell the developer of that was Indian.

DannoHung2• 17 years ago

I actually wasn't trying to be derogatory. "Do the Same" is a pretty common Indian English phrase.

Just like "Do the Needful".

redcap2• 17 years ago

And if you squint just a little bit you can understand what they're trying to say instead of getting on a rant horse about proper English grammar.

teeja• 17 years ago

Blech! I'd rather stare at cockroaches. IfYaKnowWhatIMeanAndImPrettySureThatYouDoItWasADarkAndStormyNight

IsaacSchlueter• 17 years ago

There's a lot of "short vs long" going on in the comments here. That seems silly to me.

Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher likelihood of collisions (since the search space is smaller), but are easier to "hold onto" for short periods of reading.

Thus, our conventions for naming things should take into consideration the limitations of the human brain. The length of a variable's name should be proportional to the distance between its definition and its use, and inversely proportional to its frequency of use.

Global config setting that gets specified once and used in 4 places throughout the program? 10-20 characters is probably appropriate. Might wanna go with UPPER_SNAKE_CASE to make it stand out a bit more, even.

Iterator variable that you define in a 3-line for loop and then never see again outside of it? Call it "i".

Another way to look at this: The first time you meet someone, you learn their full name. When discussing them with someone else who knows them, you use just a single name. If they're standing right there, you don't bother using their name, but just make eye contact, and maybe a "Hey". Should be the same way with variables.

grandpa• 17 years ago

> Another way to look at this: The first time you meet > someone, you learn their full name. When discussing them > with someone else who knows them, you use just a single > name. If they're standing right there, you don't bother > using their name, but just make eye contact, and maybe a > "Hey". Should be the same way with variables.

What an awesome way to think about this. Thank you.

dratman• 17 years ago

So obviously variables should be able to have more than one name: a long one and a short one. SQL offers the ability to define an alias name.

Unfortunately that would be a kind of kitchen sink feature that no standards committee is likely to accept. As a substitute, one could create a variable with a long name, then put the value into another variable with a short name, but that could be confusing unless very clearly noted in a comment.

plaes• 17 years ago

My approach is basically the same:

Long-uppercased names for anything global, settings or security-related (ie COOKIE_NAME, SECRET_HASH)

For dummy loop variables: i, j, k

For everything else I use common sense.

philluminati• 17 years ago

The same point was made in the book "Clean Code"

known• 17 years ago

Check this http://99-bottles-of-beer.net/language-perl-737.html

CodeThatDocumentsItselfSoWellItDoesNotNeedComments

Related Stories