• SCB (unregistered) in reply to Steve the Cynic
    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.

    Wikipedia gives us: Donaudampfschiffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft which, remakably, takes up less space that its English translation: "Association for subordinate officials of the head office management of the Danube steamboat electrical services".

  • Gerrit (unregistered) in reply to 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.
    In Dutch, like in German, nouns can be combined to create new nouns. Creating ridiculously long nouns like hottentottensoldatententententoonstelling (Hottentot soldier tent exhibition) is done for fun, words don't normally become that long. I don't know about German developers but among Dutch developers it is not common to build names this way.
  • Dan (unregistered)

    wow, those variables' names are as long as sandworms! [i mean, 55 comments and no Dune jokes?!? The man's called Stilgar for Shai Ulud's sake!]

  • Lego (unregistered) in reply to Gerrit
    Gerrit:
    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.
    In Dutch, like in German, nouns can be combined to create new nouns. Creating ridiculously long nouns like hottentottensoldatententententoonstelling (Hottentot soldier tent exhibition) is done for fun, words don't normally become that long. I don't know about German developers but among Dutch developers it is not common to build names this way.

    Yes! The lead developer was, indeed, German. His name, sadly, will never be remembered among the greats. He is

    Johann Gambolputty de von Ausfern schplenden schlitter crasscrenbon fried digger dangle dungle burstein von knacker thrasher apple banger horowitz ticolensic grander knotty spelltinkle grandlich grumblemeyer spelterwasser kürstlich himbleeisen bahnwagen gutenabend bitte eine nürnburger bratwustle gerspurte mit zweimache luber hundsfut gumberaber shönendanker kalbsfleisch mittler raucher von Hautkopft of Ulm

    --Lego

  • jimperrywebcs (unregistered) in reply to rant64

    Why?

    Self documenting is a false goal. Like any other kind of writing, comments should target the intended reader.

    jimperrywebcs.blogspot.com

  • nm (unregistered)

    "program flow should be optimized only after performance problem"

    ?

    This is how you do it? I must have missed the point there...

  • (cs) in reply to mx0r
    mx0r:
    "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... :)

    What? How does Obj-C encourage excessively long symbol names? A serious question -- I've written a little, but not a lot, of Obj-C.

  • OldCoder (unregistered) in reply to SCB
    SCB:
    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.

    Wikipedia gives us: Donaudampfschiffahrtselektrizitätenhauptbetriebswerkbauunterbeamtengesellschaft which, remakably, takes up less space that its English translation: "Association for subordinate officials of the head office management of the Danube steamboat electrical services".

    It sometimes works the other way, too. I once went on a branch train ride in Germany to the end of the line. When we got there, the driver said over the speakers to the passengers, "Zug ende hier", got out and walked off.

    None of the sort of spouting out you get here in the UK, for example.

  • (cs)

    This guy wasn't paying attention in CS101 when the teacher explained that long variable names are not a good thing, and when inevitably someone (me, for example) then brought up the maximum lengths silently imposed by some compilers.

    Anyway TWRTF is abbreviating as "synch" rather than "sync". Firefox even recognizes the latter.

  • WTF_WheresTheWtf (unregistered)

    Yes the names are a little long but I can see what is going on in that code and any other code you could have posted from the project. Where is the WTF?

  • willurd (unregistered) in reply to rant64

    It's called AppleScript

  • (cs)

    ItsSoBadIInitiallyThoughtItWasVisualBasic NobodyTellThemAboutPreprocessorDirectives

  • Pete (unregistered)

    I actually think this is good practice. What exactly is the problem with writing code like this?

    It makes it much easier to grasp what someone else was intending, IMO.

  • (cs) in reply to DWalker59
    DWalker59:
    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?

    I am quoting this entire post so there's a higher chance it will be read. And read again. And again.

    This is exactly what I was going to say before I read it here. Comments are for WHY, not WHAT. I can figure out WHAT by looking at the code. Obviously I'll have to understand the language to do any programming here, so I should be able to figure out WHAT from the actual code. What is not apparent is WHY that code was written in the first place and how it is supposed to interact with the rest of the program. WHY WHY WHY.

    Thank you.

  • przemek (unregistered)

    OK, so camelCase looks horrible, but it's actually not bad when converted to readable text (see below). Of course this doesn't obviate the need for comments: super-informative variable names are 'implementation comments', answering the question of 'how'; whereas the actual comments should describe the code on a high level (the question of 'why')

    switch (m_Integration_Direction)
    {
       case inventory_integration_direction.do_the_same_change_in_shop:
          do_the_same_change_in_shop(get_changed_data_from_inventory(m_last_synch_date));
          break;
    
       case inventory_integration_direction.do_the_same_change_in_inventory:
         ....
       default:
          break;
    }
    
  • (cs)

    In college, the Visual Basic textbook we used and our instructor said that we should use verbosely descriptive names for everything and that the limitations on identifier length are a thing of the past. At the time, it sort of made sense. Still, the textbook actually used intIndex instead of i! Which I was OK with, at the time, but now it's just insane.

    // This...
    For i = 0 To 10
        a(i) = b(i) + c(i)
    Next
    // Versus this...
    For intIndex = 0 To 10
        arrAlpha(intIndex) = arrBeta(intIndex) + arrCharlie(intIndex)
    Next
    After a little more experience and trying the verbose way, I eventually learned that shorter names often result in clearer code. If necessary, a comment can be left to explain what an identifier means, but when it's actually used through the code, it can make a particular operation much clearer when you use short names.
    // This...
    a = b / c * d + e;
    // Versus this...
    TotalAmount = SomeValue / SomeOtherValue * ThisEmployeeValue + _
            ThatDepartmentValue;
    It's a lot easier to scan 18 characters than it is to scan 83.
  • (cs) in reply to xtremezone
    xtremezone:
    </snip> it can make a particular operation much clearer when you use short names.
    // This...
    a = b / c * d + e;
    // Versus this...
    TotalAmount = SomeValue / SomeOtherValue * ThisEmployeeValue + _
            ThatDepartmentValue;
    It's a lot easier to scan 18 characters than it is to scan 83.

    I'm sorry, I'd rather have the descriptive names, assuming they would describe what you mean and not a name like SomeOtherValue.

    I can follow that better than a = b / c * d + e.

    I'd forget what those letters mean and have to constantly look it up every time I come back to the code.

  • (cs)

    How many times has this happened?

    • Good practice/principle stated (prefer self-documenting code)
    • Person applies principle without thought
    • People assume the principle is completely invalid

    If the original developer applied the Single Responsibility Principle, the names would be better. OO techniques and design patterns could get rid of the case statements.

    This code is a WTF. The principle is not.

  • Tim O'Brien (unregistered)

    hmmm.... I think I used to work there, and I had the same issues.

    Are you in Chicago?

  • (cs) in reply to LAN Mind
    LAN Mind:
    JohnB:
    The *real* WTF: people complaining about naming conventions in an application that truly works.

    God Lord, someone with a clue!

    A clue, but not the full picture.

    Why is the test being made? Why are we taking action for each of the cases? What other actions are we not taking that might become pertinent in future?

    Don't think that's a problem? Then please take a look at your car's suspension and tell me why it was done that way.

  • (cs) in reply to pitchingchris
    pitchingchris:

    I'm sorry, I'd rather have the descriptive names, assuming they would describe what you mean and not a name like SomeOtherValue.

    I can follow that better than a = b / c * d + e.

    I'd forget what those letters mean and have to constantly look it up every time I come back to the code.

    Oh, I'm sorry for you. How about this instead?
    amt = val1 / val2 * emp.val + dept.val;

  • barryl (unregistered)

    If you are unable or unwilling to write complete sentences in plain English(or whatever language) you shouldn't be writing code.

    I don't think comments need to tell the "why" as much as the "what" at a slightly higher level of abstraction. Not the highest level, we have specification documents and manuals for that.

    When I maintain bad code, the problem is not that things were implemented in a bone headed way. I don't care. Do it as stupidly as you want, just explain it so I can fix it and move on. OTOH, if the writer could give a plain explanation, the implementation might not be so stupid...

    And simply keeping end users happy is not the point of coding well. Making them happy today by quickly writing code that "works", is setting them up for more pain when the inevitable bugs assert themselves, and turn out to be hard to fix.

    Development speed and correct functioning are only two dimensions of quality, albeit arguably the most important. Maintainability is another, and it actually matters, even though it tends to get short shrift.

  • Brad (unregistered)

    The bigger problem is that this is (apparently) OO code that relies on casing for it's polymorphism.

  • Harrow (unregistered) in reply to evilspoons
    evilspoons:
    DWalker59:
    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?

    I am quoting this entire post so there's a higher chance it will be read. And read again. And again.

    This is exactly what I was going to say before I read it here. Comments are for WHY, not WHAT. I can figure out WHAT by looking at the code. Obviously I'll have to understand the language to do any programming here, so I should be able to figure out WHAT from the actual code. What is not apparent is WHY that code was written in the first place and how it is supposed to interact with the rest of the program. WHY WHY WHY.

    Thank you.

    FURTHERMORE:

    It is extremely rare that a professional computer programmer will open up a source file in order to examine the code for a module THAT IS WORKING PROPERLY.

    If I'm reading your code, it's because your code is not doing what world+dog expects it to do. Ever more precise and accurate descriptions of exactly how you did it wrong are not helpful.

    If you want to write a comment that has a snowball's chance of being helpful, just try to explain what the frack you thought you were trying to do in the first place.

    -Harrow.

  • Da' Man (unregistered) in reply to AdT
    AdT:
    "longSizedInteger...FormerlyKnownAsDefaultSizedInteger..."
    Yeah, I remember "TheConstantFormerlyKnownAsPi" - but now I just call it "Prince".
  • Captain Obvious (unregistered) in reply to Steve the Cynic
    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.

    The problem is even when Strassenbahnhaltestelle is semanticaly correct nobody would use it. There exists already a word for this: Haltestelle. It is generic can be used for bus, tram whatever. You can create very very long words in german which are correct but if you do so it proves that you are very bad with this language ;-)

    Deutsche Sprache schwere Sprache = German language hard language

    captcha: nimis

  • Fister (unregistered) in reply to Z

    Not changing things that are broken for fear of "system impact" is a result of occult or superstitious thinking. That has no place in software development. Your compiler will tell you when you forgot to change some reference. If you're using reflection in strange and wonderful ways, your automated tests will find the problem.

    There's a mantra I like: Just Fix It!

  • h0h0h0 (unregistered) in reply to JohnB

    Yeah totally - There isn't a WTF here. The funny thing might be that this is code that meets and or exceeds all of the naming conventions that are laid out in Uncle Bob martin's Clean Code manual.

  • Mike (unregistered) in reply to Harrow

    Sometimes the comments are there for non coders too, I'll use comments to indicate what I'm doing in addition to the why for methods so that if someone is doing a code review or an audit there's little need for my involvement. Its also a memory jog for when I dig back in. For instance take the method bool queryNetService(string ServiceAddress, int Timeout) I might include this as a comment

    /*Used for checking the status of a remote network service. Attempts a socket connection to a given service while allowing user to set timeout, return the status of the attempt. */

    In this particular instance my comment gives a brief idea of my goal and how I accomplished said goal. Within blocks of code I use brief comments to indicate how the code relates to the logic. So you might for the queryNetService example see.

    //Begin query attempt by validating remote host //Catch a DNS error //Catch an ICMP connectivity error //Initiate connection to service //Catch a service connectivity error //Return the status of the attempt

    It doesn't explain how I'm accomplishing the given steps, or why each one is necessary but it certainly narrows the focus and if someone wants to use my code who is a non-coder its easier for them to understand whats going on when they copy/paste it.

  • RKO (unregistered) in reply to rant64

    Then you want to use Fortran 77. However, I found it annoying and difficult to debug when "some var" could was the same as "somevar". Hard to search for, and some times led to subtle syntax errors.

  • RKO (unregistered) in reply to rant64
    rant64:
    We Need To Have Support For Spaces In Variables And Function Names = True;

    Then you want to use Fortran 77. However, I found it annoying and difficult to debug when "some var" could was the same as "somevar". Hard to search for, and some times led to subtle syntax errors.

  • Sean (unregistered) in reply to rant64

    "_"

  • mattmc (unregistered)

    That camel has too many humps.

  • Iago (unregistered)

    In Emacs M-x glasses-mode adds spaces within camel-case identifiers, and removes them again automatically when you save.

    Just one more reason why an ancient text editor still manages to leave modern IDEs looking clunky and user-hostile.

  • (cs) in reply to Code Slave
    Code Slave:
    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.
    There were linkers where the limit was 6.

    No, I've not omitted any digits from that.

    This was particularly a problem with older Fortran systems (leading to the bizarre cryptic naming convention in the NAG libraries) but it was true for C programs built on early Unix systems too. I for one am very glad to not be stuck in such a world...

  • franz ferdinand (unregistered) in reply to AdT
    AdT:
    Integer variables used in for loops often have horribly indescript names such as "i". Better names would be something like "defaultSizedIntegerVariableIndexingIntoEmployeesVectorWhichIsAVectorOfEmployeeRecordsEachOfWhichContainsPersonalInformationSuchAsFirstNameLastNameDateOfBirthAndRegisteredResidenceAsWellAsProfessionalInformationSuchAsJobTitleAndSalary_ThisVariableWasAddedByChiefSoftwareArchitectJohnDoeOnTheEveningOfWednesdayNovember12th2008RightBeforeDinner".

    I agree with you. There are two times/places when you need descriptive variable names in For loops:

    1. The boundary variable should be descriptive. (For x = 1 to y is bad. y should be descriptive. any stepping variable should be descriptive too).

    2. When rarely you must deeply nest a For loop, the incrementer should probably be descriptive unless you are scanning a multidimensional array.

  • franz ferdinand (unregistered) in reply to nm
    nm:
    "program flow should be optimized only after performance problem"

    ?

    This is how you do it? I must have missed the point there...

    If you think you should optimize FLOW before a performance problem happens, then you are either insane or working in an esoteric domain. Either way, a great job interview subject.

    Or perhaps we are missing the point of your objection...

  • franz ferdinand (unregistered) in reply to evilspoons
    evilspoons:
    DWalker59:
    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?

    I am quoting this entire post so there's a higher chance it will be read. And read again. And again.

    This is exactly what I was going to say before I read it here. Comments are for WHY, not WHAT. I can figure out WHAT by looking at the code. Obviously I'll have to understand the language to do any programming here, so I should be able to figure out WHAT from the actual code. What is not apparent is WHY that code was written in the first place and how it is supposed to interact with the rest of the program. WHY WHY WHY.

    Thank you.

    I didn't want to triple-post here, but I have to give a big "AMEN, PREACH IT BROTHER" to these two posts. As if I trust the "how" comments anyway - I'll be the judge of HOW your code works, thank you very much.

  • b0b g0ats3 (unregistered)

    after rubbing one out for the last 5 hours and 15 minutes, i'm finally spent.

  • (cs) in reply to Mike

    I agree fully with DWalker59, many comments should explain the why. However, there's another class of comments that Mike brings up:

    Mike:
    Within blocks of code I use brief comments to indicate how the code relates to the logic. So you might for the queryNetService example see.

    //Begin query attempt by validating remote host //Catch a DNS error //Catch an ICMP connectivity error //Initiate connection to service //Catch a service connectivity error //Return the status of the attempt

    It doesn't explain how I'm accomplishing the given steps, or why each one is necessary but it certainly narrows the focus....

    I disagree with him that the purpose of these comments is to enable a non-coder to copy/paste. Rather, it would allow me to skip to where there is an ICMP error without paying attention to the rest of the function. Sometimes comments explain why, sometimes they index the code.

  • aoeu (unregistered)

    "Constantinopolitanischerdudelsackspfeifenmachersgesellschafft!"

    (the bagpipe manufacturer's guild of constantinople)

    "Nihilistendynamittheaterkaestchenssprengungsattentaetsversuchungen!"

    (outrageous attempts by nihilists to blow up the strong box of a theatre with dynamite

  • Ouch! (unregistered) in reply to Captain Obvious
    Captain Obvious:
    The problem is even when Strassenbahnhaltestelle is semanticaly correct nobody would use it. There exists already a word for this: Haltestelle. It is generic can be used for bus, tram whatever. You can create very very long words in german which are correct but if you do so it proves that you are very bad with this language ;-)

    Deutsche Sprache schwere Sprache = German language hard language

    That's not quite correct. There are circumstances in which normal people actually use the word Straßenbahnhaltestelle. For example, if you're giving directions, you'd e.g. say "Turn right at the Straßenbahnhaltestelle." if in that street there's a Bushaltestelle something like 100 yards from the Straßenbahnhaltestelle. But in general people opt for the shorter generic word, that's true.

    CAPTCHA: Donaudampfschiffahrtsgesellschaftskapitänskajütentürschlüsselanhängerbildersammlerkongreß WTF?

  • Mr.'; Drop Database -- (unregistered) in reply to rant64
    rant64:
    We Need To Have Support For Spaces In Variables And Function Names = True;
    Some languages allow it, though it's a seldom-used feature. SQL: SELECT [column one], [column two] FROM [table name]; Lisp family: (|function name| |parameter one| |parameter two|)

    And then there's VB 6, which allows nonbreaking spaces in variable names, but that seems more accidental than anything.

  • meno (unregistered) in reply to Bim Job
    Bim Job:
    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.
    Wait... are you implying that many programmers are humourless, impractical egomaiacs who pursued a career in computers because of their poor interpersonal skills?

    Say it aint so.

  • unbelieveroz (unregistered)

    Reminds me of my days as a young developer when our lead developer refactored some code and renamed a particularly notorious - but still very, very occasionally needed - function to 'IfYouUseThisFunctionIWillKillYouMyself'.

    I survived to post about it.

  • mainframe_web_developer (unregistered) in reply to AdT
    AdT:
    Integer variables used in for loops often have horribly indescript names such as "i".

    It's a Fortran-thing.

  • Xythar (unregistered) in reply to ProgrammerThatNeedsToFitCodeLinesInto80Characters
    ProgrammerThatNeedsToFitCodeLinesInto80Characters:
    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.

    Yeah, and how long did it take you to figure out the process? Even if it only took a couple of minutes, how are the long variable names better than a simple comment at the start describing exactly what you just said:

    // Synchronise changes between inventory and shop. In the case of a conflict, the shop wins.

    A one line comment before the code and you save yourself a whole lot of unreasonably long variable names, making the code more readable AND easier to understand.

    The real WTF is the number of commenters here who have no problem with writing code like that. I hope you guys are all sockpuppets of the same troll or something.

  • ubercoder (unregistered)

    I don't get it. What's the problem?

  • Herby (unregistered) in reply to mainframe_web_developer
    mainframe_web_developer:
    AdT:
    Integer variables used in for loops often have horribly indescript names such as "i".

    It's a Fortran-thing.

    Not really, it dates back to mathematics and their conventions. Many times "i" was the small integer that was iterated. Fortran just kept the convention, and (originally) decided that ALL variables beginning with I, J, K, L, M, N (no lower case in those days) were integers as well. If you worked in "that era" you saw things like "ICASE" which was an integer variable probably the case number or something similar (things like "KASE" were used as well). Now everyone (we hope) declares variables as to their type (int, float, long, double, etc...) so we don't need such things, but at times they persist.

    As for comments in general, the following works quite well for me: Write the comment for yourself, for in 6 months, you will probably forget what you were doing and the comments ought to let you figure it out. Forget this at your peril!

    Sure, you can have long variables, and sometimes they DO make sense, but that is ONLY ONE documentation method. There are many others, including comments.

  • Shinobu (unregistered)

    I've seen a lot of code that I wish looked like this. I'll be honest, I use a lot of 1-char variable names myself, but I restrict those to local function variables, loop counters for example. Method names should be long and descriptive. The only reason that at first glance you're overpowered by the sea-of-letters-syndrome is that you can't use spaces in variable names. Now, you can use the non-breaking space, but that potentially creates visual ambiguity (<class> <identifier> vs. <identifier with a space in it>) and is harder to type. We need a good solution to the problem that doesn't have such drawbacks.

Leave a comment on “CodeThatDocumentsItselfSoWellItDoesNotNeedComments”

Log In or post as a guest

Replying to comment #:

« Return to Article