2 Replies - 1163 Views - Last Post: 26 August 2013 - 10:27 AM

#1 Zel2008  Icon User is offline

  • D.I.C Addict

Reputation: 14
  • View blog
  • Posts: 790
  • Joined: 06-January 09

Commenting and documentation

Posted 24 August 2013 - 11:17 AM

Hi all,

I'm curious what everyone thinks -- does anyone else ever get frustrated out of their mind when people refuse to comment or document their code, and then it takes a miracle to interpret or modify it? I'm not saying I'm perfect at it myself, but it seems, more and more, that standard formats for documentation, good commenting practices, and putting in a little extra effort to make sure something is maintainable and comprehensible, gets thrown aside in favor of speed, especially in corporate America.

It's driving me up the wall -- I just got my first corporate job of my career, and the difficulty in understanding other people's code is staggering. There have been multiple times that I've been actively discouraged from documenting my code.

I understand that it's all about speed, but it seems counterintuitive to me -- wouldn't making time for these standards and making time to develop a system to make documentation easier save a significant amount of time and confusion in the long run? We have no documentation team, no standards team. Our QA people make sure the code works, but completely ignore the quality of its format.

Is this normal and common? What has everyone else run into? And is there any way to stop myself from completely pulling out my hair at the sheer inefficiency of it?

Thanks,
Zel2008

Is This A Good Question/Topic? 0
  • +

Replies To: Commenting and documentation

#2 Skydiver  Icon User is online

  • Code herder
  • member icon

Reputation: 3479
  • View blog
  • Posts: 10,724
  • Joined: 05-May 12

Re: Commenting and documentation

Posted 24 August 2013 - 09:30 PM

I used to be a zealot about commented code. Now, I'm a zealot for minimal comments in self documenting code. I became a convert because after being burned too many times by inaccurately documented code. When I first entered the industry, I made the incorrect assumption that the documentation would match the code. Was I ever wrong. And it wasn't like I could walk over to the person's office/cube who wrote the incorrect documentation and give them an earful. Quite often the person has moved on to another job or become a VP and it becomes a career limiting move to give them an earful.

Anyway my reasoning for minimal comments on self documenting code is this: You created the high level design document, then you created the detailed design document. Now as you write the actual code or fix bugs, the rubber hits the road. If you were documenting the code, you would not only have to fix the code, but also fix the comments associated with the code, as well as the detailed design document, and if need be, the high level design document. Also if you are doing things right, you should also be updating the specifications and maybe the requirements document if needed. Most places don't bother going back up the chain.

So you may argue that doesn't excuse you from updating at least the code and its comments. Here's my bullheaded counter argument: The code should be self explanatory. Only if there is a subtle concept or a design decision that was influences why the code was written a particular way should there be comments inserted.

I've become a big believer in the DRY principle. Don't Repeat Yourself. If you had this (strawman) code, don't you see the redundancy:
//
// ComputeProduct
//
// Summary:
//    Returns the integer product of a integer multiplicand and an integer multiplier.
//
// Details:
//    Multiplies an integer multiplicand by an integer multiplier and returns the product.
//    No checks are done for integer overflow.
//
// Parameters:
//    int     multiplicand    An integer multiplicand.
//    int     multiplier      An integer multiplier. 
//
// Returns:
//    int    product of the multiplicand multiplied by the multiplier
//
// Exceptions:
//    None.
//
// Error returns:
//    None.
//
int ComputeProduct(int multiplicand, int multiplier)
{
    // Return the product of integer multiplicand multiplied by the integer multiplier
    // Don't bother checking for integer overflows.
    return multiplicand * multiplier;
} 



In my eyes, this is sufficient:
int ComputeProductWithNoOverflowChecks(int multiplicand, int multiplier)
{
    return multiplicand * multiplier;
} 


Of course, coding with this style tends to screw over the current crop of "Intellisense" dependent programmers. It's why I use SlickEdit and Source Insight instead of Visual Studio.

It's not a matter of writing more documentation. It's a matter of writing more understandable code.

Quote

Programs must be written for people to read, and only incidentally for machines to execute.
- H. Abelson and G. Sussman (in "The Structure and Interpretation of Computer Programs)


Quote

The way to make programs easy to read is not to stuff them with comments... A good programming language ought to be better for explaining software than English. You should only need comments when there is some kind of kludge you need to warn readers about, just as on a road there are only arrows on parts with unexpectedly sharp curves.
- P. Graham (in "Hackers and Painters" footnote 9, pg. 224)


and my favorite:

Quote

Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer.
- S. McConnell

Was This Post Helpful? 3
  • +
  • -

#3 cfoley  Icon User is offline

  • Cabbage
  • member icon

Reputation: 1940
  • View blog
  • Posts: 4,028
  • Joined: 11-December 07

Re: Commenting and documentation

Posted 26 August 2013 - 10:27 AM

Quote

I just got my first corporate job of my career, and the difficulty in understanding other people's code is staggering.


If you are starting in a new place of work, then you have to expect to spend some time getting to grips with the codebase. If it is your first programming job then there will probably be some strange looking idioms that will be second nature in 6 months time, both reading and writing. Commenting them would be like the // end for loop comments that newbies insist on.

Of course, code should be readable but for me, writing a comment is an admission of defeat: I was either unable to structure the code is a self documenting manner or I was unable to name things descriptively and unambiguously. Some things require documentation (like public APIs) but that's a separate issue.

I can't speak for the company you work for. It could be that the code is a mess and also uncommented, in which case your complaint is more valid.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1