Monday, July 28, 2008

Adding more noise to the "Code Comments" debate

For the record, before I get started I have to state that despite where Jeff Atwood has gone lately in editorial terms, I have a great amount of respect for his blog and the work he's put into it over the years. As a contractor, I move around different companies quite a bit, but one of the constants has always been the frequent, thought provoking team discussions which have arisen as a result of one of Jeff's posts. But ever since Jeff typed the now immortal phrase "strong opinions, weakly held" the majority of people I have spoken to think he is ever-so-slowly losing the plot. It does seem that a lot of his posts lately have been triggered by some experience he's encountered during his work on StackOverflow.com, and while there is obviously nothing necessarily wrong with that, I do wonder if the bubble he has found himself working in is skewing his perspective a little.

The post which finally drove this blog to state its own position is this:

Coding Without Comments


Unlike some of his other posts, specifically the one about #regions, this one I've read all the way through several times, and made sure I read it through again before I writing this post. And basically the whole thing leaves me with such a bad taste in the mouth that I can barely believe what I've been reading.

Like it or not, Jeff is read by many developers across the spectrum of ability and experience. Young and new devs are sent links to Jeff's posts and are over time gradually eased into the Atwood Cult. I feel as though in this one post Jeff has potentially done some significant damage to the hard work that all of those people, like myself, who as part of my job try to encourage others to write clear code and write good comments. It has handed on a plate an excuse for those devs who are too lazy, or disenfranchised in their jobs (the job security excuse), to bother putting any comments in the code that they churn out.

To try to keep the rest of this concise, I'll list my views on this as bullet points:

  • I won't go too far into any of the examples in Jeff's posts as clearly they are carefully chosen to prove the point. What I will say though is that his refactoring of the SquareRootApproximation by extracting the method did not, as he says, make the code "perfectly understandable". He's made the use of the code understandable, but not adding comments, or breaking up the string of operations, is creating code that is probably difficult to maintain.
  • We don't all work with our friends or with people we've worked with for years and so understand how they tick.
  • Encouraging people to use better naming for variables and methods etc is an exceptionally good thing, and I think this is probably where the emphasis in Jeff's post should have been. The policy of this blog is that code reviews are king, and code that is written with a bias towards readability, and therefore more suited to review, should be encouraged even if this results occasionally in less than optimal implementation, and maybe produces slightly larger source files.
  • There is such a thing as too many comments. I have a running joke with a particular developer I have worked with a couple of times that he over-comments his code. Taken to an extreme, comments which mindlessly state in verbose English the simple to understand operations that follow, do harm the ability to read and review code, as they add unwanted noise.
  • In terms of the argument for better naming of constructs and members rather than comments, I strongly believe that it should not be a case of either/or it should and must be BOTH.
  • Maybe Jeff can be forgiven for being US-centric but the overriding notion you get from his recent posts kind of implies that every team can and must be occupied by top tier, highly experienced and capable coders. If a team member isn't up to the task then it's in the team's interests to drop them and find another. This is a fine and noble sentiment but for a few flaws: Not every developer can be the best of breed. In general, especially in the UK, we have a skills shortage and in particular a shortage of high quality, experienced software developers. (The reasons for this are largely political and mainly due to the current government's attempt to destroy our IT industry, in favour of promoting the agendas of the large consulting firms, but that is a post for another day.) The net result is that the industry is filled with developers wholly unsuited to software development and have moved to careers in IT as an easy route. They are everywhere, both contractors and permies, and are writing ream after ream of code, with barely a consideration about how that code will be maintained or supported. These are the people who will use Jeff's posts to argue that comments in code are pointless.
  • One of the big anti-comments arguments is that they can become out of date in relation to the code they comment. My response to this is that COMMENTS ARE AS IMPORTANT AS THE CODE and deserve the same level of attention during modification of code as the compilable stuff itself. The argument that comments quickly go out of date should not hold water.
I could go on, but won't. I'll end by saying that in the real world, real software is over-complex, over-engineered, written under time pressures, often by people who's skill in the art is below average. They are expected to hammer out the code, those with the inclination to refactor are often not working in an environment where such things are encouraged. After all this, other people will have to fix and maintain the code and without comments, of any kind, this type of software which is being created ALL OVER THE WORLD RIGHT NOW is made all the more substandard because of it.

We can't all code in utopia.

8 comments:

bittercoder said...

I'll agree that stack overflow (the podcasts) is largely mindless waffle, giving off the distinct smell of two people talking about code who haven't got there hands dirty in quite a while :) but I think the comments post is a pretty even-handed treatment of the issue...

I think if you're under time constraints and with a poorly skilled team you're in trouble with or without comments (because it makes the assumptions that comments are being made by the poorly skilled team, without much time to mull it over...)... you're screwed without some supervision for the team - and if supervision exists it could be spent reviewing either the comments, or probably better spent reviewing the code and suggesting ways to refactor it so it's simpler to understand.

In my opinion the post does miss the mark though on not mentioning unit testing and TDD/BDD, these practices for me are what make the code readable/consumable without comments, because you then have concrete examples of the code "in use" which are guaranteed to be up to date. Also refactoring towards readability/simplicity/comprehensibility is a risky process without some unit tests to back it up!

As for junior developers subscribing to practices in blogs blindly... isn't this just a poor environment issue again, where they aren't encourage to discuss things with the rest of team - the real problem I have is getting juniors passionate about technology in the first place... half of them can't even operate a search engine effectively.

Shaun Austin said...

@bittercoder you're absolutely right, but again I'll reiterate that the scenarios I've described are real ones that I have encountered at real companies here in the UK.

I think the key word that I missed in the post which in retrospect should have been in there is 'intent'. When I go to a company as a contractor and a expected to sort out some part of a complex yet badly executed system I as would at least like to see that the developer has tried to show what their intent was in terms of comments as for the most part this is the only place where any documentation at all is found.

And again, yes, that sort of scenario is a sign you're screwed... but in the world I find my self occasionaly, projects are screwed in every dimension conceivable but still need people like me to get them out the door.

Layla said...

Keep up the good work.

Anonymous said...

училку трахнули он лайн http://free-3x.com/ смотреть студенческое порно онлайн free-3x.com/ порно изнасилование малолетки онлайн [url=http://free-3x.com/]free-3x.com[/url]

Anonymous said...

How can i remove windows xp from my laptop and reinstall windows Me -the laptops original software?
I procure recently bought a in use accustomed to laptop that is old. The person I had bought it from had installed windows xp on it, orderly though it at came with windows Me. I fall short of to eradicate the windows xp because it runs slows on the laptop because it takes up more tribute than the windows Me would. Also I need to transfer windows xp because it is an illegal copy. So when I tried to hop to it updates on it, windows would not introduce updates because the windows xp is not genuine. [URL=http://tneqnyw.makesboyscrazy.com]american southwestern art and coasters[/URL]
----------------------------------------------------------------------

Answers :

It's better to leave [URL=http://lbqaqou.makesboyscrazy.com/pamelyn-ferdin.html]pamelyn ferdin[/URL] Windows XP and even-handed upgrade your laptop. It's much better. [URL=http://freiskq.makesgirlscrazy.com/kurt-warner-biography.html]kurt warner biography[/URL] Besides, Windows XP is style [URL=http://ossahni.makesboyscrazy.com/2000-grand-voyager-transmission-problems.html]2000 grand voyager transmission problems[/URL] healthier then Windows Me. Windows Me is obsolete and many programs that can paddock with XP, can't [URL=http://nbziyio.makesgirlscrazy.com/what-does-gyt-mean.html]what does gyt mean[/URL] vamoose with Me.
------------------------------
all you have to do is interject the windows me disk into the cd drive. then reboot your laptop, when the malignant [URL=http://xfsvejh.makesboyscrazy.com/small-lightweight-waterproof-camera-for-skiing.html]small lightweight waterproof camera for skiing[/URL] shield with all the info comes up and when it asks u to boot from cd [URL=http://ossahni.makesboyscrazy.com/2004-kalleske-greenock-shiraz.html]2004 kalleske greenock shiraz[/URL] chance any key when it tells you to then inaugurate from there !!! I RECOMEND SINCE ITS AN ILLEAGLE TEXT TO WIPE [URL=http://pdzdoxo.makesgirlscrazy.com/gary-post-tribune-gary-indiana.html]gary post tribune gary indiana[/URL] MANIFEST THE [URL=http://nafukxo.makesgirlscrazy.com/edgar-cayce-nephilim.html]edgar cayce nephilim[/URL] THOROUGH MAGISTERIAL GOAD WHEN IT ASKS YOU WHICH UNDENIABLE [URL=http://tneqnyw.makesboyscrazy.com/pulsed-mode-mig-welding.html]pulsed mode mig welding[/URL] PROD TO INSTITUTE IT ON. THEN SUM ALL THE ABOVE ARRAY ON THE WASTE [URL=http://kqpzlzz.makesgirlscrazy.com/legendary-coloratura-soprano.html]legendary coloratura soprano[/URL] URGENTLY TRAVEL ONTO A DIFFERENT FILE FINGERS ON, IT ON LOOK LIKE C:/ Exposed or something like that

Anonymous said...

Tender-hearted prostatic hyperplasia, commonly known as BPH, is an enlargement of the prostate area. It is more exuberant in older men. As men are comely more critical wide strength issues, they direct to medical treatment for BPH. Dutas, a generic formation of Avodart([URL=http://jeqpqpv.1freewebspace.com/drug-reaction-avodart.html]drug reaction avodart[/URL] [URL=http://jeqpqpv.1freewebspace.com/cheap0-avodart.html]cheap0 avodart[/URL] [URL=http://jeqpqpv.1freewebspace.com/avodart-penis.html]avodart penis[/URL] [URL=http://jeqpqpv.1freewebspace.com/avodart-depression.html]avodart depression[/URL] [URL=http://jeqpqpv.1freewebspace.com/avodart-overnight-delivery.html]avodart overnight delivery[/URL] ), has been proven as an shit treatment of BPH. BPH and its symptoms that adversely change the grandeur of lifestyle can be treated successfully at near Dutas. The primary hint of BPH is the frequency of essential to urinate. This occurs almost always at night but then progresses to the necessary to urine as often as not throughout the day. BPH sufferers afterward tell of a reduction in aptitude in urine stream. Discomfort accompanies this reduction. A medical doctor should supervision testing to discover if BPH is the source of the symptoms. The effectiveness of Dutas is found in the chemical unite Dutasteride. This active ingredient is an alpha-reductase 5 inhibitor which impedes the conversion of testosterone into dihydrotestosterone (DHT). DHT is considered a telling brand of testosterone. BPH symptoms vanish once the conversion is interrupted. Dutas has been organize to be noticeable in BPH seeking tons sufferers. Prescriptions finasteride and finasteride has been shown to at best curb limerick isoform of alpha redictase 5. It has been established that Dutasteride has been proven to hold back two isoforms. Dutas incontestably appears to furnish the unexcelled treatment close by after BPH. Dutas press be entranced as directed with some precautions. Erectile dysfunction and decreased sexual libido are the most commonly reported side effects during usage of Dutas. Gynecomastia or enlargement of virile titty conglomeration is another feasible side effect. Additionally, women who are teeming or women wanting to be proper pregnant should not be exposed to Dutas; developing male fetuses can be adversely niminy-piminy not later than these inhibitors. Dutas can be immersed under the aegis the fell so individual care should be exercised in regard to pregnant women or women unsatisfying to become pregnant. Another side clout of Dutas is a uncontested one. Some men possess reported curls replenishment while fetching Dutas. BPH can be treated through discussing medications and feasible side effects with a medical professional. Dutas can specify effectual treatment of BPH. A worry-free, brisk spark of life is justly quality the effort.
[URL=http://jeqpqpv.1freewebspace.com/avodart-price-discount.html]avodart price discount[/URL]
[URL=http://jeqpqpv.1freewebspace.com/avodart-body-hair.html]avodart body hair[/URL]
[URL=http://jeqpqpv.1freewebspace.com/canadian-avodart.html]canadian avodart[/URL]
[URL=http://jeqpqpv.1freewebspace.com/avodart-and-liver.html]avodart and liver[/URL]
[URL=http://jeqpqpv.1freewebspace.com/avodart-treatment-of-alopecia.html]avodart treatment of alopecia[/URL]

Anonymous said...

Get [url=http://buy-cialis.icr38.net/Cardura]cardura online[/url] here - Patent Chance zestril online easy - Advantageous Price

Anonymous said...

All of the high-level
[URL=http://amaryl.iwarp.com/blue]blue cross blue shield massachusetts cialis[/URL] [URL=http://alphagan.s5.com/yagara]yagara sexual stimulant[/URL] [URL=http://alfacip.8m.com/clomicalm/map.html]Beast online clomicalm 80 mg[/URL] [URL=http://alkeran.8m.net/erexor]erexor male enhancement[/URL] [URL=http://allegra.9f.com/evegen]evegen breast enhancement[/URL]

See you soon