01 Dec 2009, 07:28
Generic-user-small

James Waletzky (1 post)

Liz and Rachel,

Firstly, congrats on a well done book! There are lots of great tips for coaching agile teams that many people will put to good use.

There was one small tidbit I strongly disagreed with. Liz made a note on page 158 entitled “No Comments” stating that the team should be encouraged to avoid writing comments because they clutter the code and cannot be relied upon to be accurate. Good code is supposedly clear and obvious without comments. I disagree wholeheartedly.

Inaccurate comments are mostly due to laziness and lack of attention to detail, which also leads to bugs. Additionally, even with a well named variable or function, the INTENTION of the code may not be obvious. Good comments address the “WHY” of the source code, which is not obvious in any other way. It is true that comment blocks may be a sign that refactoring (e.g. extract method) is needed, but that should not preclude intention comments. I blog a bit about this at http://blogs.msdn.com/progressive_development/archive/2007/08/28/motley-says-code-comments-are-for-sissies.aspx (note that the title of the blog is intentionally the opposite of the message).

In strongly encourage you to revamp this piece of “advice” for future editions as it could lead a junior developer astray. Comments are a necessity, particularly when you can keep your low-level design documentation in the code and generate docs in a nice format afterward (e.g. C# XML comments).

James.

27 Dec 2009, 08:46
Lizsmall_pragsmall

Liz Sedley (1 post)

Hi James,

Thanks for your post.

I agree ‘No Comments’ is too strong. What I meant to say, was ‘Very very few comments’. But I do think it is possible for most code to show intention.

Good reasons for adding comments are when it is not obvious why one algorithm was chosen over another, or when you are addressing a work around in a 3rd party library. Normally front end code is littered with ‘workaround for ie7’ etc.

The other exceptions is what you mentioned, when documentation needs to be generated from code. This would apply if you are writing an API that would be exposed outside the company. Even then be very careful about just generating documentation from comments left in by developers. How much useless documentation have you read that was generated that way?

But if your api is not exposed outside the company, I strongly suspect that any generated documentation will not be read.

Liz Sedley

28 Jun 2010, 22:26
Picture_14_pragsmall

Tim Ottinger (6 posts)

Here is our take on commenting: http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html

This means you should almost never write comments. If you need a comment, it is because something in the language or library is wrong or inobvious (which is a kind of wrong also).

The documentation for code is and should be the comments and the names used. Comments don’t get read, and don’t make code readable. But the urge to write a comment often is telling us that the code is not readable. They’re really as much a salve for guilt as a tool for communication, except as given in the link.

But that’s my opinion, and nobody paid to hear it, so….

18 Mar 2013, 15:40
Rachel-profile_pragsmall

Rachel Davies (5 posts)

I agree with Tim here.

26 Apr 2013, 18:11
Generic-user-small

Josh Woodcock (1 post)

If Agile is a way of thinking and we are striving to improve and increase communication, how does adding clarification to code with comments reduce communication? I sincerely hope I never hear someone tell me that another Agile coach told them to comment less or not to comment at all.

  You must be logged in to comment