Comment On CodeThatDocumentsItselfSoWellItDoesNotNeedComments

Lovely code... I've seen some just like that :)

:O

DamnThatIsSoWrong!

80085 80085

Real programmers don't need comments - the code is obvious.

If the code is not obvious, it was hard to write. If it was hard to write, it should be hard to read.

(from Real Programmers Don't Use Pascal)

SelfExplanatoryCommentSoObviousItDoesNotNeedToBeAdded

"Objective-C" ... anyone? :)

(I love Obj-C, it was in no way a criticism) -- long variable/method names are sometimes justified, so I would not consider it as a WTF.
On the other hand, trying to write self-commenting code by (and being proud of) it IS certainly a WTF... :)

So where is the WTF here?

Employing a case switch instead of the Strategy pattern?

GotPaidByTheCharacterNotByLinesOfCodeThisTime. NothingWorseThanTakingTheRightTheoryAndAbusingItToThePointOfInsanity. ThankGodForAutoCompletionOrNoFunctionsOrMethodsWouldEverBeCalledCorrectly.

IWouldHaveThoughtHeWouldHaveLookedAtItAtSomePointAndSaid 'YouKnowThisActuallyMakesItHarderToFollowPethapsThereIsAMiddleGround'

I always use OverlyDescriptiveCamelCasedJavaMethodNames(), what's wrong with that?
[/sarcasm]
And I thought DependenciesProductnameFile.addCallRelation was too long...

Hmm, could be a nice complexity metric: longest method name in a system ;)

it is what it is: self-documenting code... none of that icky meta-commented code that doesn't comment on its code but needs a seperate comment to add comment to the code to comment it

ntu:

it is what it is: self-documenting code... none of that icky meta-commented code that doesn't comment on its code but needs a seperate comment to add
comment to the code to comment it

<!-- this comment describes some of the main differences between self-documenting code without comments and code that doesn't need seperate comments to comment about the cde it comments on -->

HowWouldHaveThoughtThatSomebodyWouldBeSoImaginativeAsToWriteTheirCommentsWithNoSpacesJustLikeInTheOriginalArticle

Personally, I also don't see where the WTF is: readable code, documented in a way that the documentation changes together with the code (i.e. no comments that are bound to become out of date because the code changed). I like it.

Sorry, I just don't see a WTF here. So what if the names are long? I've seen far too much code with short names and no documentation; here there is at least some "on initial viewing" idea of what the code is doing.

If you want short names while modifying the code then a quick search-and-replace will accomplish that. If you want documentation in the code then add it.

But it's the end result that counts and, to quote Alex, "culminated over a decade of design and development experience into a clean, almost-perfect application."

What's the end objective people: keeping the coders happy or keeping the end users happy?

The *real* WTF: people complaining about naming conventions in an application that truly works.

I wonder if the lead developer was German? I think it is quite common among German developers to create names in a way that Germans create nouns ... just mix every word in a sentence and create a new noun.

"Donaudampfschiffahrtsgesellschaftskapitän", which in English becomes four words: "Danube steamship company captain.

Which works find until you hit the 256 character limit (assuming c++) and the compile can nolonger distinguish between veryLongStringOld and veryLongStringNew. Even more interesting results in some older versions of C where the limit was (as I recall) 32.

This Halloween I'm coming to the office as a program comment. No one will recognize me.

Charles400:

This Halloween I'm coming to the office as a program comment. No one will recognize me.

This Halloween's a Saturday so there's no way I'm going into the office.

"No Mr Saleman, a WTF on your part does not constitute an emergency on mine."

The caption says "Comment On CodeThatDocumentsItselfSoWellItDoesNotNeedComments".
I don't see why.

If you don't see what's wrong with the code, consider adding a third place to update data.

I'll check back when I'm finished writing my GetSum class. I'm on GetSumOfFourPlusFive right now.

Yes, the names are a little too long, but maintainers time won't be wasted trying to find out what b_x_01 is. Yes, that's a variable name for business_rule_number_1 which is business_rule_check_duplicated_values.

I think people are confusing two concepts here. There's self-documenting code, which is code so obvious, you don't need comments:

void bankruptcy() {

  foreach(Employee e in this.employees) {

    e.dispose();

  }

}

Then, there's self-commenting code, which is code which embeds the comments into the code itself, probably creating redundancy:

void ChristmasBonusFor2009() {

  foreach(Employee currentEmployee in this.ListOfEmployees) 

{

    if(currentEmployee.performanceWasAdequateInThePreviousYear) {

      currentEmployee.giveThemABonusForGoodWork(100);

    }

  }

}

(Obviously-contrived example is obviously-contrived, but hush)

Interestingly, in .Net languages, the latter style actually does have a (miniscule) run-time performance impact, as the method names and such are not compiled into addresses, etc. And, never mind if your language is interpreted!

So, in summary, use regular comments! They're free!

JohnB:

Sorry, I just don't see a WTF here. So what if the names are long? I've seen far too much code with short names and no documentation; here there is at least some "on initial viewing" idea of what the code is doing.

If you want short names while modifying the code then a quick search-and-replace will accomplish that. If you want documentation in the code then add it.

But it's the end result that counts and, to quote Alex, "culminated over a decade of design and development experience into a clean, almost-perfect application."

What's the end objective people: keeping the coders happy or keeping the end users happy?

The *real* WTF: people complaining about naming conventions in an application that truly works.

Hmmm, well then, I was hoping you could explain this:
DoTheSameChangeInShopThenDoTheSameChangeInInventoryForNotChangedDataInInventory

What does that mean? How do you perform a change in inventory for a not changed data in inventory?

Thanks!

Hi, long time reader, first time poster!

I kid you not when I say I've seen a single line (in C) of more than 450 characters ... in production code. The author followed exactly the principle described here. Needless to say it was completely unmaintainable code bulging of bugs and ended being rewritten from scratch (and the original author downsized ...).

Jester:

I wonder if the lead developer was German? I think it is quite common among German developers to create names in a way that Germans create nouns ... just mix every word in a sentence and create a new noun.

"Donaudampfschiffahrtsgesellschaftskapitän", which in English becomes four words: "Danube steamship company captain.

Or the one I was told about when I was in school:

Strassenbahnhaltestelle == Tram Stop. (Street railway stopping place, allegedly). The German version is not as impressively long as the captain's, but the contrast in length is awesome.

@Deprecated:

Hmmm, well then, I was hoping you could explain this:
DoTheSameChangeInShopThenDoTheSameChangeInInventoryForNotChangedDataInInventory

What does that mean? How do you perform a change in inventory for a not changed data in inventory?

Thanks!

Isn't it obvious. You just need to read the code!

JohnB:

The *real* WTF: people complaining about naming conventions in an application that truly works.

God Lord, someone with a clue!

Man, I hate it when people think that a comment is supposed to say WHAT the code is doing.

A comment is supposed to say WHY the code is doing what it is doing; why it's not doing something in a different way that, at first glance, you might think would be a simpler and functionally equivalent way of doing the task; why the code as written performs well in spite of conditions X, Y, and Z; and what the environmental expectations are at this point in the code. Long variable and method names do not obviate this.

/* Add one to A */
Set A = A + 1

Why are we incrementing A here?

AdT:

Integer variables used in for loops often have horribly indescript names such as "i". Better names would be something like "defaultSizedIntegerVariableIndexingIntoEmployeesVectorWhichIsAVectorOfEmployeeRecordsEachOfWhichContainsPersonalInformationSuchAsFirstNameLastNameDateOfBirthAndRegisteredResidenceAsWellAsProfessionalInformationSuchAsJobTitleAndSalary_ThisVariableWasAddedByChiefSoftwareArchitectJohnDoeOnTheEveningOfWednesdayNovember12th2008RightBeforeDinner".

Even version control can be made obsolete by self-documenting variable names. Think of "longSizedInteger...FormerlyKnownAsDefaultSizedInteger..."

This is actually the best variable name ever. just from reading this simple Integers name, i know what that loop does, what i can get from it, and what is the meaning of life.
But i still think you left out some vital information about the software like what that guy had for dinner and where did he spend his summer.

I don't have a problem with long variables names. But the variables names need to be of actual use. And what the hell is wrong with adding comments?

How about something like:

switch(mIntegrationDirection)
case ChangeShop:
// Apply changes to shop. Change has already been applied to Inventory.
SetShopData(GetInventoryData(mLastSynchDate));
break;

case ChangeInventory:
// Apply changes to inventory. Change has already been applied to shop.
SetInventoryData(GetShopData(mLastSynchDate));
break;

etc...

Shorter names, more comments, easier to understand.

Gaaah that code is so rough I am getting Carpal Tunnel just looking at it...

I actually found that quite clear, at least in context:

1. First you take the changes from 'the shop' and apply the to 'the inventory'.

2. Then you take the changes from 'the inventory', but only those for items that weren't affected ("changed") by step 1 (i.e. where the change wasn't made obsolete by step 1) and apply those to 'the shop'.

In other words: two-way synchronize changes, in case of conflict 'the shop' wins.

IMO sheer length is not the WTF here. The only WTF I see is that names should describe what an operation means, not how it works.

If everyone involved understands the meaning, then something like 'SyncShopToInventory', 'SyncInventoryToShop', 'TwoWaySyncShopWins', 'TwoWaySyncInventoryWins' are OK names for some of the constants or methods.

But if you have to account for people on the team (or in maintenance) who may not have an understanding of some of the more abstract concepts involved, then using names that describe what happens to the data may in fact be the better approach.

OTOH I wouldn't want to work in a shop where that is the case.

Is there *any* good thing that does not become harmful when overdone?

Remko:

Personally, I also don't see where the WTF is: readable code, documented in a way that the documentation changes together with the code (i.e. no comments that are bound to become out of date because the code changed). I like it.

Hi TopCoder!

Steve the Cynic:

Jester:

I wonder if the lead developer was German? I think it is quite common among German developers to create names in a way that Germans create nouns ... just mix every word in a sentence and create a new noun.

"Donaudampfschiffahrtsgesellschaftskapitän", which in English becomes four words: "Danube steamship company captain.

Or the one I was told about when I was in school:

Strassenbahnhaltestelle == Tram Stop. (Street railway stopping place, allegedly). The German version is not as impressively long as the captain's, but the contrast in length is awesome.

Tram ticket machine was my favourite, Strassenbahnfahrkartenautomaten (literally "Road train go card machine"). The colour of a tram ticket machine would therefore be something along the lines of Strassenbahnfahrkartenautomatenfarbe...

When I was in school I always heard that "speed limit" had a rather long translation in german: Geschwindigkeitsbegrenzung

Caffeine:

GotPaidByTheCharacterNotByLinesOfCodeThisTime. NothingWorseThanTakingTheRightTheoryAndAbusingItToThePointOfInsanity. ThankGodForAutoCompletionOrNoFunctionsOrMethodsWouldEverBeCalledCorrectly.

IWouldHaveThoughtHeWouldHaveLookedAtItAtSomePointAndSaid 'YouKnowThisActuallyMakesItHarderToFollowPethapsThereIsAMiddleGround'

If I was being paid by the character I'd have spaces (underscores?) in my function names and demand payment for them. I'd also demand payment for my overly descriptive comments.

CAPTCHA : acsi - dyslexic character encoding?

Yeah it's verbose, so? OK It's a lot verbose; in fact it is over the edge. Didn't the guy ever hear of abbreviations? Still not a WTF though.

Tram ticket machine was my favourite, Strassenbahnfahrkartenautomaten (literally "Road train go card machine"). The colour of a tram ticket machine would therefore be something along the lines of Strassenbahnfahrkartenautomatenfarbe...

Not really. Die Farbe des Straßenbahnfahrkartenautomats would be the right form.
It would be possible to compose a word, but it will be done only if a new useful category is created. The colour of a tram ticket machine is obviously not a concept for itself. The eye color, for example is, so that the Augenfarbe will be composed.

Code Slave:

Even more interesting results in some older versions of C where the limit was (as I recall) 32.

For identifiers with external linkage, you were guaranteed a mere 8 significant characters.

I've worked on C code in the past which had to be portable to such systems. The fix was to have a header containing.

#define ABC_MyNicelyNamedFunction ABC001
#define ABC_MyOtherUsefulFunction ABC002

which made symbolic debugging a little dull, but at least it allowed you to use sensible naming in the code whilst avoiding linker errors.

I prefer to not have to use the horizontal scrollbar more than the vertical scrollbar when reading code

catcha: jugis. excuse me?!

what gives?
a) compilers don't give a sh** about your var names
b) the writing is done by the IDE with auto-completion/refactoring anyway

i have a bonar

That's NeXT's fault, not Objective-C's fault. And Apple's fault for carrying over the old interfaces and strange naming conventions.

Objective-C/Cocoa method names were the first thing I thought of, too. Some examples, and these are recently added functions, not hold overs from NeXT:

managedObjectContextsToMonitorWhenSyncingPersistentStoreCoordinator
from iPhone SDK: willAnimateSecondHalfOfRotationFromInterfaceOrientation

I would've added links, but this forum thinks they're spam.

gallier2:

Tram ticket machine was my favourite, Strassenbahnfahrkartenautomaten (literally "Road train go card machine"). The colour of a tram ticket machine would therefore be something along the lines of Strassenbahnfahrkartenautomatenfarbe...

Not really. Die Farbe des Straßenbahnfahrkartenautomats would be the right form.
It would be possible to compose a word, but it will be done only if a new useful category is created. The colour of a tram ticket machine is obviously not a concept for itself. The eye color, for example is, so that the Augenfarbe will be composed.

You're wasting your time with these people. They're not interested in category theory, and they're not interested in linguistics. I like to think that they're interested in post-modern ironic defence of the absurd, but frankly most of them just sound like bit-headed morons.

Frankyboy:

what gives?
a) compilers don't give a sh** about your var names
b) the writing is done by the IDE with auto-completion/refactoring anyway

Ignoring the limitations of compilers (already mentioned) and the limitations of IDEs, and the limitations of refactoring (which is not at all the silver bullet that its proponents claim it to be), there's a slight problem here.

What about the poor sodding maintenance programmer who has to untangle this bollocks?

And, of course, with Objective-C the arguments are named as well, so that could make the methods even longer. Like this method of NSBitmapImageRep:

initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel: