• Prime Mover (unregistered)

    Looks autogenerated to me. Someone wrote a tool to build / update an interface automatically, and at some stage wrote a bulkload of comments into it as well, probably to make sure it was written correctly. Never stripped out those comments after having "finished".

  • (nodebb)

    Some of the Indian and Chinese companies pay their programmers per line of code. Guess, some managers are dumb/smart enough to not distinguish between actual code and comments, thus, inflation.

  • MaxiTB (unregistered)

    This is an greater issue of mandatory documentation. I also worked in companies in the past where mandatory documentation was part of the process (sorry for my language); it's all nonsense, usually made up by clueless people (seriously, who hasn't read clean code by now).

  • 516052 (unregistered) in reply to Andre Alexin

    I newer understood why people use comments for that though. I mean, writing pointless comments is boring. And there are so many fun and creative ways you can play around with to inflate the size of your code. And many of them come with either a plausible excuse or better yet make your code utterly unmaintainable by anyone else.

    Seriously, if you are paid by LOC have fun with it.

  • Code Refactorer (unregistered)

    We had to use an API from another company for our java project and all methods were auto-commented. For example method setDate(int day, int month, int yr, int index). And the comment above was this: This method will execute the setDate functionality. Param int day The Day. Param int month The Month. Param int yr The Yr. Param int index The Index. Spending some hours, we figured out that 31 February was allowed to be set (which resulted in 2nd or 3rd march) and that the month was not zero-based. But we never figured out the meaning of "index", no matter how hard we tried. So I can imagine following scenario: Manager: "We sold our demo code to the customer, but he wants a description of all the methods he can use.". Programmer: "All our methods have no comments. I don't like to comment each method now, it's a boring work. And sometimes I even don't know what the method is doing at all, it is too long ago when I programmed it. But no worries, I can quickly and aeasily write a tool to auto-generate the comments. We can provide him this as Javadoc for our API.".

  • my name is missing (unregistered)

    In my first job at a defense contractor in the early 80's, our customer was the Air Force, and they wanted any code shipped to them be documented with a flow chart. So someone built a flowchart generator, one symbol per page with lines going to the edge of the page and referencing a page number. The average flowchart was about 18 inches thick.

  • (nodebb)

    The problem with the doxygen bits of those comments is that there's no actual descriptive text there, just the bits that you'd anchor the descriptions to. The information that's in them as they stand is exactly the stuff that doxygen really can generate for you. The non-doxygen parts are no better, and indeed include totally irrelevant stuff; who gives a stuff what IDE was used to write the code?

  • (nodebb)

    We had a guy here who would put comments in his code in Russian (he was from Georgia). Not a big deal, since translators have been around for a long time so we could copypasta and find out what the comment means. He did a lot of coding here, and not a lot of it has comments other than something at the top of the code that says, in English, "Program to populate phone list" or "Program to extract data." No indication as to what kind of data in the comment, but the code is mostly readable. He left a few years ago to work for a big tech company overseas, and none of us has remained in contact with him (because he wasn't the kind of guy you want to be friends with).

    The ONE time we needed to see what the comment said because we didn't understand what his code was trying to do while trying to fix a bug, we ran the comment through a translator. It said, "This is the same thing I did for <untranslatable>." That could have been a company, a particular manager, a software project, who knows? But I'll give him credit for putting in a comment where it was needed -- useless as it was to anyone but him.

  • Argle (unregistered)

    When I taught programming, I rejected useless documentation. I discovered that far too many other professors encouraged really bad documentation. Like this:

    int a; // declare an integer

    I told my students not to waste time on this garbage. My general advice: say what's not obvious or don't say anything. I still love the old adage: "There's a fine line between being terse and being cryptic."

  • Aitkiar (unregistered)

    In my work i have a never ending fight against comment that indicates where start and where ends a bug fix. There are places of the code like this all over the application.

    // bug 12345 start some code ... // bug 12345 end

    And when several bugs target the same hotspot in the code you end with things like this.

    // bug 12345 start some code ... // bug 12346 start some code ... // bug 12347 start some code ... // bug 12347 end // bug 12345 end some code ... // bug 12346 end

    all complete useless and misleading

  • (nodebb) in reply to Argle

    When I was in college in the 80s we were taught to make comments about our declared variables. But instead of this useless thing

    int a; // declare an integer

    we were taught to do this

    int a; // Index for Applicant array

    If you're going to bother, make it useful. To this day, I will make these comments where they are needed, and I sometimes will use comments to keep track of what data lives in what field position of a CSV file

  • (nodebb) in reply to 516052
    Seriously, if you are paid by LOC have fun with it.

    Because the people who are paid by LOC, usually aren't good enough to even know how to have fun with it.

  • Sole Purpose Of Visit (unregistered)
    // Function name   : Paula::Frist
    // Machine         : RedPill
    // Environment     : IBM 3600 Cobol. (Note to Paula -- update as required)
    // doxygen         : 
    /// \fn   		Frist! Frist! Frist!
    /// \brief	        Paula Beans Are The Best!	
    /// \details		
    /// \param		Bean Input	
    /// \param		Another Bean Input		
    /// \param		A List Of The Remaining Bean Inputs
    /// \return		Brillant!
    /// \author		(redacted) Check with Paula before updating this field
    /// \date		12.31.1999 23:59:59
    
  • Sole Purpose Of Visit (unregistered) in reply to CodeJunkie

    I think the point of being paid by LOC is to make money out of it.

    Those of us who are not total propeller-heads prefer to have fun with money. But YMMV.

  • (nodebb)

    I'm building stuff for a government customer. I'm actually going to have to ask for contractual approval to give them actual .h/.cpp files instead of cutting and pasting the text into a thousand page Word document. These headers tacked onto a source code file have nothing on a real WTF.

  • (nodebb) in reply to Bananafish

    int a; // Index for Applicant array

    ... and why not use a descriptive name instead?

    Though my favorite anti-pattern from our code base are non-descriptive verbose names like

    i_counter
    

    Which leaves me wondering if

    components [i_counter]
    

    is using the correct counter while being no terser than

    components [i_component]
    

    would have been.

  • (nodebb)

    .Net? This is C++, no? That's the biggest WTF...

  • Loren Pechtel (unregistered) in reply to Bananafish

    I call things like

    int a; // declare an integer

    school comments because so many professors wanted comments about the obvious, you had to say something even if nothing was needed.

    int a; // Index for Applicant array

    is better but

    int Index; or int ApplicantIndex;

    would be superior. The only reason I can see for int a; would be in QuadraticSolver() or some other such thing that normally refers to an A. Otherwise it's a code smell.

  • (nodebb)

    @R3D3: so, "i_counter" is reverse Hungarian notation?

    @Loren Pechtel: I agree that "int ApplicantIndex" is the "definitively descriptive variable name" but:

    for (ApplicantIndex=0; ApplicantIndex < Applicant.size(); ApplicantIndex ++ ) { <something> Applicant[ApplicantIndex].getName() <something else> <more code> Employee[ApplicantIndex].save(); }

    But if we used "int a; // Index for Applicant array" wouldn't "Applicant[a].getName()" and "Employee[a].save()" be 1- Easier to type; 2- Less prone to typos; 3- Be more readable; 4- Avoid confusion when some other array needs to use the same index?

    There's a lot of potato-patahto in here, I'll give you that

  • SomeDude (unregistered) in reply to Loren Pechtel

    …or because you are not allowed to go beyond 80 characters on a line, so using short identifiers (and keeping the function short) is better than breaking up every expression between multiple lines.

  • Sole Purpose Of Visit (unregistered) in reply to bradwood

    I'd imagine that Visual Studio C++/CLI announces itself as Visual Studio .Net, if somehow you can find a way to query the IDE in question.

    But sure. Go ahead. If, in your world, that's the real WTF, then have fun with the WTFs that you can't be bothered to see.

  • Sole Purpose Of Visit (unregistered) in reply to CodeJunkie

    To be fair, you can both have fun with LOC and also make money out of it. Here's how!

    You remember those childhood games where you ask for a number between 1 and 100, then ask a convoluted set of calculations, and then say "Aha! The result is 33 1/3?" Well, the same applies here. And the genius part of it is, you can have fun and automate it.

    Let's say you're in an environment with what would sensibly be a constant tolerance of, say 1.0 millimetres. (CAD does this stuff all the time.)

    Let's say there are several possible externalities -- various graphical entities from points to lines to infinite planes. The great thing about generics is that you can create the following monkey patch in, say, C#:

    public static double CreateMetric(this T cadItem, double tolerance) where T: IGeo
    {
       // Play silly childish game here, essentially transforming the input tolerance to the exact same output tolerance
    }
    

    This is a boon for several reasons:

    1. You are enforcing the appropriate constant. Why leave that to the compiler?

    2. You are enforcing ISU standards. (You might want to wrap that double into a class that converts millimetres into millimetres, which is even more LOC, and clearly "future-proof")

    3. You can trivially automate the process, using some sort of templating (say T4 or Scriban), or if you are especially adventurous, an expression tree. Obviously this would be a local automation, and you would then use cut and paste.

    4. If your manager claims you are lazy and not producing enough lines of code, you can simply add more childish questions to CreateMetric(). Presto!

    I can't think why I've never tried this ...

  • Sole Purpose Of Visit (unregistered) in reply to Sole Purpose Of Visit

    As a bonus, btw -- automating the creation of unit tests for this excrescence will multiply the LOC by a substantial amount.

    And all managers love unit tests, even though not a single one of them has ever once read a single line of any of them.

  • (nodebb) in reply to 516052

    To have fun with it you must be able to have fun, and these people are often reduced to bio-robots by this point. Not to mention that if they have to resort to comment inflation they probably aren't skilled enough to invent something.

  • 516052 (unregistered) in reply to Aitkiar

    Those can actually be very useful. In my last job there were a number of non intuitive edits in the codebase that look like obvious errors or at the very least superfluous but were in fact workarounds for bugs in the platform we were working with. And we were running into new ones all the time. So wrapping them in comments did a lot to prevent the next guy from "fixing" your fix away next time they fork.

  • (nodebb) in reply to Sole Purpose Of Visit

    Heck yes... My direct manager wants me to make unit tests for our code, even though our code lacks units... We'd need automated high-level result tests first, before refactoring the code is realistic. We are talking about a monolithic industrial code base of 20+ years in the growing, so retrofitting unit tests to components, that rely on the globals-based "interface" of other code parts, is a gargantuan task, and would likely just end up codifying the bad structure that useful tests would help fixing.

  • (nodebb) in reply to Bananafish

    for (ApplicantIndex=0; ApplicantIndex < Applicant.size(); ApplicantIndex ++ ) { <something> Applicant[ApplicantIndex].getName() <something else> <more code> Employee[ApplicantIndex].save(); }

    The verbosity is indeed an issue. I am using Fortran mostly at work, which is overall very verbose but has more useful constructs for basic iteration tasks (DO i_component = 1, SIZE(component_array)).

    1- Easier to type; 2- Less prone to typos;

    Should not be relevant. Typos are easier to fix, than mixing up indices. Mostly, because they can be caught at compile time. Plus, any recent text editor helps with completion, which also helps to avoid typos.

    3- Be more readable;

    Depends on the context. But yes, a is at least more readable than i_counter, which just mixes the worst of both naming choices. Readability starts to suffer, when you have a,b,c,d though. In numerical code at least, significantly nested loops are common.

    4- Avoid confusion when some other array needs to use the same index?

    If I see employees[iApplicant] I suspect, that it is intentional, because it would have been too obvious a mistake to make. If I see employees[a] after reading int a; // applicant index 50 lines earlier (100 for equivalent Fortan code...), I suspect that something might be wrong, and start reading the context to check.

  • (nodebb)

    General agrement, but multiuple considerations:

    1. Code comments for extraction, processing and advanced analytics are quite powerful. Of course manually adjusted ones that contain additional information are more valuable than simple "clones".

    2. Far too few comments [either in the code directly, in the SCM commit message - hard to analyze/track] provide the WHY for the code (that what may be understandable from the code). This is where a linked work tracking system with the ability to capture the context of why the work was being done is so important.

  • (nodebb) in reply to R3D3

    R3D3 - as a consultant who has successfully helped many with that exact scenario, it is fairly simple [especially with manager buy in]. ANY change to a section of code gets estimated, executed, and accepted only if the appropriate refactoring and multi-level testing has been performed. NO exceptions, NO "this is a critical fix"....... Yes, it can be very difficult to get agreement from upper management, but it can be done - hang in there.

  • (nodebb) in reply to 516052

    Noting a bug in the platform is different from just slapping a bug/story number in the comment. There's a big difference between:

    // BUG12345 Begin
    string realApiOutput = HtmlDecode(rawApiOutput.Replace("&amp;", "&"));
    // BUG12345 End
    

    and:

    // The API double-encodes ampersand (and only ampersand), so we have to decode the &amp; entity twice. 
    // This behavior caused BUG12345.
    string realApiOutput = HtmlDecode(rawApiOutput.Replace("&amp;", "&"));
    

    I've worked where the vast majority of our code was in multi-thousand-line SQL stored procedures and the database wasn't under source control, so the former was fairly common. It was a tool for code review, but even then it wasn't really necessary. Comparing the sproc in Dev to the one in Stage, using something like Beyond Compare, the changed lines are highlighted anyway.

  • Mike Rosoft (unregistered)

    It's like a device with a number of components, connected with wires, each wire being duly marked with labels, but the label on the yellow wire says: "Yellow wire". (Or, occasionally, the label on the red wire says: "Green wire.")

  • 516052 (unregistered) in reply to Eric Ray

    True.

  • (nodebb)

    COBOL has fairly similar (mandatory!) comments at the beginning of each block of code. It requires author and all kinds of junk that's not really useful.

    I do like to comment each function, to say what is passed in and returned, even if it should be obvious. But I put a short description of each variable passed and returned, not the types since they're already in the declaration (at least in Python, Java, C, etc.)

  • (nodebb)
    Comment held for moderation.
  • kaewberg (unregistered) in reply to hwertz

    "Cobol fingers" is a term :-) The main code is also very verbiose.

  • clubs21ids (unregistered)
    Comment held for moderation.
  • Spamcourt (unregistered)

    The fact that it seems to be for a RAID controller is something I quite don't like.

  • gnasher729 (unregistered) in reply to 516052

    I remember one rather complex function where I had ten workarounds for various things. Every single one well documented, what exactly went wrong if you didn't do which workaround. Some exotic, like something going wrong without a workaround if you used a belarus keyboard.

    And then someone announced proudly how he had so much simplified this code and it was now down to one third of the original size and so much easier to understand. I looked at it - he had just removed all the workarounds without bothering to see why they where there.

    So I sat down, typed in some simple text, and it went wrong. Then I let him try it out himself, and it was wrong again. He couldn't understand it. I showed him what code he had removed that had fixed the problem. And asked him to look at the other problems. I never checked up on it.

  • treu skincare (unregistered)
    Comment held for moderation.
  • Framingnoone (unregistered) in reply to Argle
    Comment held for moderation.

Leave a comment on “Commentary”

Log In or post as a guest

Replying to comment #552713:

« Return to Article