Comments on: Show me your code comments and I’ll show why you don’t need them

By: Bruce

Bruce — Wed, 19 May 2010 16:37:53 +0000

@Dave: To me, your argument seems to be that when you extract a method, you have something potentially reusable, and when it’s reusable it can be reused in a wrong way. Well, I think the benefit of having reusable code available far outweighs the risk of “abuse”.

You say “..if it doesn’t make sense to do that code block in isolation from its caller…”. Why would anyone do it if it doesn’t make sense? If someone tries to use that method in a different context, it’s probably because it does make sense. But obviously they can’t assume that it will work perfectly right away. Still, they’re better off trying than writing duplicate code.

The more interesting question is, what can you do to make the method and the class less likely to fail when it’s reused? That’s where terms like decoupling become relevant.

By: Community News: Comments on Commenting | Cole Design Studios

Community News: Comments on Commenting | Cole Design Studios — Mon, 04 May 2009 17:14:02 +0000

[...] Reiersol takes a more pragmatic approach to the issue and wants to see the code before making a decision on whether the comments are needed or [...]

By: In Defense Of Commenting | BrandonSavage.net

In Defense Of Commenting | BrandonSavage.net — Mon, 04 May 2009 16:35:52 +0000

[...] article from last week, “On Code Commenting and Technical Debt” raised a lot of response throughout the community. I think that discussion is great, and I’m all for a debate that [...]

By: Dave

Dave — Mon, 04 May 2009 08:40:13 +0000

When writing comments you should treat them like you’re telling of a historial fact. You can tell when someone writes subjective comments, and that’s indeed not the right way to go IF the intentions of the author deviate from the actual purpose of the code.

However, if you’re working with a team of developers and you have to spend time in eachother’s code from time to time you’ll be glad that they’re there. If you have to make adjustments to a 400-line function and all the comments you got are the ones in the PHPDoc, the chances are you’re going to try look for “clues” in the rest of the class as to how some variables are treated. Proper naming conventions help a lot in this case, but usually you want that extra bit of information.

On the point of commenting for yourself, I’ll go with Brandon’s point of view. If you write several thousand lines of code each week you’re bound to forget how a certain function you wrote 4 months ago was made.

By: dagfinn

dagfinn — Fri, 01 May 2009 20:08:49 +0000

Code that’s hard to understand without comments will be improved by adding comments. That much we agree on. And, yes, the comments may be helpful when refactoring. That is, if they haven’t deteriorated to the point where they become misleading.

By: Brandon Savage

Brandon Savage — Fri, 01 May 2009 18:56:09 +0000

One of the biggest reasons I still comment, though it didn’t fit with my argument regarding technical debt, is that my memory is imperfect. Writing a comment about a particularly unusual line of code or about the logic I used is often a perfect reminder to me about why I did something or how I did something.

I honestly think that commenting code is a practice that operates shop-by-shop, and the standards should reflect the developers and their personalities. I doubt there’s one “correct” way to comment your code, just like there’s not one “correct” version control system or one “correct” bug tracker. It’s preference-based.

My article reflects my personal view on commenting but is by no means authoritative on the subject as a whole. That said, commenting underperforming code *will* help you pay down that technical debt when the refactor comes, because you’ll have an easier time understanding it and perhaps the comments will lead you to it.

And if you tell me that you write no underperforming code ever, well, then I don’t know what to tell you…

By: dagfinn

dagfinn — Fri, 01 May 2009 12:31:37 +0000

The more interesting question is, what can you do to make the method and the class less likely to fail when it’s reused? That’s where terms like decoupling become relevant.

By: Dave

Dave — Fri, 01 May 2009 11:45:53 +0000

The other problem of course with pulling methods out is that someone can then later call that method from an unexpected place, where assumed prconditions are not met for example. Visibility scope isnt necesarily a fix for this either since when extending functionality you’ll invariably have access to the new method. Visibility is really more a solution for separating interface from implentation.

A method should encapsulate a unit of reuse, if it doesnt make sense to do that code block in isolation from its caller then it shouldnt be a separate method.

By: dagfinn

dagfinn — Fri, 01 May 2009 10:56:47 +0000

As for the idea that commenting requires practically zero effort, I disagree. It’s just like any other explanatory text. Making sure it’s accurate and communicates well is real work. And it’s even more difficult to remember to update comments correctly, which is why it’s frequently not done and comments turn out to be actively misleading and therefore worse than no comments.

By: dagfinn

dagfinn — Fri, 01 May 2009 10:51:31 +0000

The objection about onion code is somewhat valid, but if it gets that bad the problem is probably that you haven’t got your abstractions straight. If you just have lots of methods and they’re not logically organized into classes, you will get that kind of problem. I will grant you that that may be more difficult than just extracting methods. One important piece of that puzzle is what Neal Ford calls SLAP (Single Level of Abstraction Principle) as in the presentation I was referring to in my previous blog post.