Sign in / up

back to article Comment judiciously, refactor if needed, avoid the 'f' word

Comments can be abused as easily as any other tool or technique. You know comments - and, indeed, the project - have become dysfunctional when you start to see gripes and swearing, or flames concerning either the code or the individual who wrote the code. When the Windows 2000 source was leaked a few years back the code was, …

COMMENTS

House rules Send corrections
This topic is closed for new posts.
  1. Anonymous Coward
    Anonymous Coward

    Comments are a tool

    Overuse of a tool is (can be) bad. Underuse is inefficient.

    Throw out all your hammers. What will you do with your nails now?

    0 0
  2. Anonymous Coward
    Thumb Down

    Rubbish

    "But do question the need to add a comment, and refactor or rethink the code if it needs it."

    I'm currently having to decipher a bunch of stuff that was written many years ago, using UML/Use cases/etc. with pretty designs and generic statements like "find the order" and so on.

    The code is naturally not commented at all. There's nothing at the beginning of a routine that says what it's for nor how it relates back to the designs. There's no justification anywhere for why things are done in certain ways (there being multiple ways of doing things in this app). There're no comments explaining where the code uses the in-house coded objects and there's little documentation on the in-house coded documents available and in any case, these things have been butchered over the years to get them levered into something where it was convenient. The stuff has been re-factored and re-thought to split it into supposedly appropriate subroutines.

    In short, instead of having to read tons of subroutines and lines of code to find out what's called by what and where, a few comments in the code at strategic places would explain what, why and how and I'd be vastly more productive than I am now and the boss would be happier.

    Comments not needed? Bollocks.

    0 0
  3. Dr. Mouse

    Reminds me

    ... of my university days.

    During my first year of an electronic engineering degree I was told that "Your lab book is for your use alone. It can be a mess, but put anything in that you want, so long as you get the details in so you know what you've done". They asked that our lab books were handed in once, to make sure we WERE getting all the data we needed in them, but told us they wouldnt do that again, it was our responsibility.

    I then took a year out, moved universities, and changed to mechatronics. About a month into my first lab, we were told to hand in our lab books. I didn't have any time to change what was in there, and was marked down for bad language (at the end of one session I had realised I had made a mistake in one calculation right at the beginning, so the entire 2-hour lab session had been wasted, including the start of building the circuit, so I had written something like "WASTED THE WHOLE F***ING LAB BECAUSE OF ONE MISTAKE! AARGH!").

    In short, they told me that it WASNT just for my benefit, employers wanted the books in case you get hit by a bus, so you end up having to assume that EVERYTHING you write down (in a lab book, code comments etc etc...) will be read by your boss, and his boss, and the CEO of the company, and the client... Irritating, but the way the world works.

    0 0
  4. Brian Meadows

    Some people can't manage

    So let me get this right, programmers leaving obscene comments is an argument for not commenting? Nonsense. I've run my share of programming teams, and ANY programmer who put obscene comments in the code, let alone left them in the final version, would find out very quickly that it wasn't appreciated.

    Sensible commenting IS an enormous aid when you have to take over someone else's code. I've been there, done that, far too often in my contract days to be convinced otherwise.

    0 0
  5. Steve Evans
    Flame

    I've literally just...

    I've literally just had a good bitch at one of my colleagues in a source comment, and you know what, it's staying there!

    If he'd consulted me on his proposed modification to the database structure before implementing it, I wouldn't be here with a single SQL query containing 3 derived tables and 7 joins! I've spent an hour trying to find a misplaced bracket! Grrrr!

    To be honest I hope he pulls the source off the SVN and reads it!

    0 0
  6. Solomon Grundy

    Comments Required

    Comments are just as important as the code itself. Otherwise you get what I call the 'Stonehenge' effect: in years to come no one will remember how to use it, or even what it does. Resulting in some coder saying, well, we just have to start all over again because this doesn't make any sense. (sort of like extreme coding, haha)

    The projects I lead are not complete until they are fully commented. Comments are part of the developers job, and if they can't get them done in a normal working day, that's too bad - they're either working late or taking it home.

    0 0
  7. The Other Steve
    Thumb Down

    I _like_ swearies in comments, me

    And as always, I shall roll out my own cut'n'paste comment about coding standards and guidelines, thusly :

    Coding standards and style guidelines and suchlike should be discussed, designed, and agreed upon by individual coding teams, not globally set by some one pontificating on the web.

    Different mixtures of ability, language, culture and toolsets lend themselves to different processes. What's best is what's best for _you_ not what's best for someone else.

    To be honest, I'm getting a little tired of of being told how I should I run my development process by other people with some notional 'guru' status, (or even worse, occasionally by one of their disciples with little or no practical experience but a very fundamentalist attitude).

    I might not be Kent Beck, but I've quite enough skill and experience to sort it out for myself, thanks. I'm sure I'm not the only experienced coder to feel this way either.

    0 0
  8. Graham Bartlett

    How many times do we need to flog this dead horse?

    Another day, another article about commenting. Oh joy.

    The second-to-last paragraph says it all. Code says "what and how", comments say "why" and add any other details not apparent from the code. But this has been the standard opinion amongst all professional software engineers for years. XP tried the "no-comments" system as a reaction to over-documentation, and all real software engineers quickly found that actually there was a *reason* some of that documentation existed. We know this now, and we've known it since approximately 6 months after XP was first invented.

    So why yet another article on the same bloody subject? Please, enough already.

    0 0
  9. Anonymous Coward
    Flame

    Real world

    The people who write these things seem to live in some Utopian environment where code is written, compiled, executes perfectly first time, is archived away and never looked at again.

    Unfortunately, most of us work in places where we have hundreds of apps written in a dozen languages for several different OS's. There may be 200 code revisions for a single app spread accross more than one source-code tool.

    I spend half my life figuring out which is the most current version of a piece of code after the source-archive has crashed (again) and a job, started two years ago, but put on hold umpteen times due to "resourcing issues" and then revived with a changed spec due to....

    Life's crap and things go wrong. Get a job in the real world before you start lecturing us on what comments should or shouldn't be used for. The most useful comment in the world starts.

    /* 01/01/2003 - Change 465 - Reason:....

    and ends

    /* end code change 465

    Usefull, well-structured comments have saved the arses of those of us working outside pristine-white labs so often they won't be disappearing any time soon, no matter how many unit tests you use to document.

    0 0
  10. mh.
    Coat

    'tards

    Oh wait, this *isn't* about El Reg's word of the day.

    On commenting, I think it's a judgment call. I've done a lot of tech writing stuff because there's no documentation at all and support needs to know exactly why a particular error message occurs. A lack of comments in the code mean I've got to work out what's going on and it can be tricky if it was written several years ago by someone who's long since left the company. Call it silly names like "code smells" if you will, but the right type of comments make it easier to maintain and support code. Paying an experienced developer to read and document someone else's uncommented code is a lot more expensive than getting the original developer to spend a few seconds explaining what's going on and why they did things in a particular order. "If we don't do that it costs us money" seems a pretty compelling argument to me.

    0 0
  11. Anonymous Coward
    Anonymous Coward

    Why I comment

    There are two reasons I comment my code:

    1. The comments get read by a documenter so I don't have to write and maintain a separate documentation library. I have found that separate documentation is rarely up to date or comprehensive enough to be useful.

    2. It saves me time when I have to fix my own code several months later. There's nothing rewarding about being on site trying to find and fix a bug in a routine you yourself wrote. Only last month I found one of my own comments that read something like:

    //This block seems to work but if it's a problem then rewrite it (split the function into two loops?) rather than trying to find the issue.

    Sure enough, that was the problem and splitting the function into two loops did work. Without that one line comment then it could have taken significantly longer to find and then fix and the only person I could have blamed was myself.

    However, I can see how keeping your code free of comments is a great idea if your code works first time and never goes wrong...

    0 0
  12. Anonymous Coward
    Anonymous Coward

    Obscene comments can be useful too!

    For example, I once resorted to using foul notification language in a pop-up box displayed at program launch in some internal-use-only beta test code, for the explicit purpose of ensuring that the fools in Sales would do as they were told and NOT release immature, unsupported code to customers (a third time).

    Naturally, the sales folks complained bitterly when they ran the (explicitly warning-labeled) code (probably on customers' equipment), but the tactic DID have the intended effect, and the code stayed in-house where it belonged. My response to management's complaint was to remind them of exactly WHY this was done, and the wanton disregard of procedures by Sales that had made it necessary.

    Of course, it would never have come to this in a department that wasn't seriously dysfunctional...

    0 0
  13. Anonymous Coward
    Gates Horns

    Why weren't the comments removed by the compiler?

    I can see strings in compiled code, they serve a purpose.

    But why isn't the compiler removing the comments? Even if they had some value the optimization would make their location meaningless.

    0 0
  14. Anonymous Coward
    Anonymous Coward

    It was ever thus...

    I remember, some xxx years ago, when IBM used to release the source code of their various operating systems on microfiche, that some (non-British) customer had complained bitterly that one comment in a comms code module read:

    "Retry 10000 times, for the hell of it".

    The programmer had been required to change the comment, so that next time round the source code line read:

    "Retry 10000 times"...

    0 0
  15. Curtis W. Rendon
    Boffin

    no comments?

    Over documentation?

    I thank you for demonstrating XP is rubbish.

    I suggest you move on to a useful methodology.

    0 0
  16. Anonymous Coward
    Anonymous Coward

    Three cheers

    for comments containing those naughty naughty words that mustn't ever be read for fear of corrupting the delicate wallflowers that read code. I think it should be obligatory to put a minimum half a dozen of such into each service, to help such folk acclimatise to real life and real people and real frustrations, and such like. It's a service to one's fellow beings.

    0 0
  17. JamesH

    Comment comment 2

    Oops. Forgot to mention. Could one of the reasons Vista is so damnably slow, is that the code has been split off in to hundreds of methods, hence piling on the overhead of calls? Yes, the compiler should inline a lot of it, but not all....

    0 0
  18. JamesH

    Comment comment

    Firstly - Bollocks.

    Secondly - The dial should go up to 11.

    0 0
  19. Anonymous Coward
    Stop

    @The other Steve

    "What's best is what's best for _you_ not what's best for someone else."

    I'm sorry, but unless your employer is paying you to just mess around and amuse yourself, what's best is not what's best for you, but what's best for the team that you're a part of. Sure, nobody likes an overbearing prick who thinks he knows what's right for everybody, but then again, nobody likes a cowboy who won't listen to anyone except himself. The *purpose* of comments is communication; if you're talking to anyone other than your own reflection in the mirror, you need to speak in a common language.

    0 0
  20. mh.
    Gates Horns

    Swearing

    Anyone else find themselves sniggering when they were doing Windows API programming and discovered the shItemID structure, not to mention the pointer to an ID list (or PIDL)? I think a certain MS bigwig could do with washing his mouth out with soap and water.

    0 0
  21. Anonymous Coward
    Anonymous Coward

    vulgarity

    One of my colleagues was working on code from a third party when he found the an error message that printed "Fuck me, no memory left". He emailed the team alias asking "should we change this?", and promptly got a reply from our (we thought somewhat straitlaced) manager: "Of course. It isn't internationalized" ...

    0 0
  22. Steven Burn
    Boffin

    Absolute tosh

    For around 95% of my code, there's only myself that see's it, and even in those cases, I add comments to let myself know where I've put everything. In small projects this isn't too necessary, but most of my projects are over 1000 lines of code, and if you think I'm gonna leave out comments, return to the project a few months later and struggle to remember where I put everything, then you're having a laugh.

    No serious programmer will leave code uncommented. The fact the comments may contain profanity or whatnot, is neither here nor there.

    0 0
  23. Mark Rendle
    Thumb Up

    RTFA

    I realise that reading the article properly before posting comments is a tiresome process, but it's often worth it. If you did, you might notice that Matt is advocating sensible commenting in tandem with good readable code. You might also have noticed that his book is sub-titled "The Case Against XP". You might then look like less of an idiot.

    0 0
  24. Sandra Greer
    Boffin

    Comment first!

    Back in the dark ages, when I was a consultant who designed and wrote mostly COBOL, I learned to create "stubs" for routines I would write later. The standard was to create the start and exit labels, plus the description of what the routine would do. We called it "structured programming". In COBOL the calls were "PERFORM a THROUGH b" (where a and b were labels), so the calls could be commented as well. The compiler turned these into the appropriate assembler for calls.

    This made it possible to do extremely complex tasks in an extremely primitive language. I'm still proud of my COBOL, though I haven't looked at the stuff for 25 years or so.

    It's still not a bad idea, and makes consultant code readable long after the wanderer has drifted elsewhere.

    0 0
  25. Anonymous Coward
    Anonymous Coward

    @ Dr. Mouse

    I studied computer science at university.

    My first project was marked down because there weren't enough comments in the code.

    My second project was marked down because there were too many comments in the code.

    I gave up after that, and really just spent the next three years getting drunk.

    0 0
  26. Oliver Watkins

    hey

    Matt,

    Haha, Couldn't help smiling when I read this article. You're right about swearing, but having said that I do think that swearing adds another dimension to the How/What/Why... a dimension called the developers 'emotional level'..ie. how emotionally frustrated a developer is with the method. The more swearing in comments the more a candidate for refactoring it becomes.

    How are things going on the project? We should catch up for lunch sometime. How are the two newbies going?

    Oli

    0 0
  27. Diogenies
    Alert

    Code reviews

    No wonder windows is a mess - if any code had been reviewed the naughty things would have been cleaned up pronto !

    0 0
This topic is closed for new posts.