Neal Ford writes that comments are a code smell:
We were on a project where the client insisted on Javadoc comments for every public class and method. We started the project adding those comments, but eventually stopped. When doing agile development, you don't want anything that hampers refactoring. Having comments in place caused a dilemma: do I refactor the method and change the comment (the most work), refactor the method and leave the old comment (with the theory being that I'll change it again later, and would rather just have to update the comment once), or not refactor? No good options here. Having pervasive comments discourages refactoring because it adds significant extra friction. On this project, we abandoned commenting as we went along. The last week of the project we literally did nothing but go back and add comments to the code, which worked well because the code base had settled down by that point. But notice what's lurking in wait: the client wanted all the comments there to make it easier to maintain in the future. But who's to say that whoever maintains that code will keep the comments up to date?
Neal's post is very worth reading. He says the Lysol to clear away this particular smell is made of two things: automated tests and composed method, which is Kent Beck's name for the technique of creating large numbers of very small methods with very clear names. He also offers an explanation to one interesting mystery, that of why this approach is so much more popular in Ruby and Smalltalk than it is in Java: dynamic languages encourage descriptive method names. Check out the comments on Neal's post; he didn't explain that in much detail, so I asked him for follow-up. My guess is that he sees this as a side effect of the more natural syntax dynamic languages use.
The quote I pulled out raises a different issue: what do you do when your client wants something you can't recommend? Like any consultancy, ENTP encounters this question every once in a while. Neal's example is a great example because it's not cut and dried. The Javadoc comments may have established an obstacle to refactoring and clean maintenance; on the other hand, they resulted in extensive documentation, and extensive documentation is a good thing.
My personal answer is that you let the client know, but you also let the client decide. I'm not sure what the official ENTP answer is. The official ENTP answer could be different on comments, too. I feel the same way about comments in code as I feel about adverbs in writing. In a perfect world, it would never happen, but in reality you have to give way occasionally.
Loading tweets…
Our Products
Our Open Source Projects
- astrotrain – simply the best email processing solution out there.
- Seinfeld – automatic tracking of your open source contributions to github projects.
- warehouse – still using subversion? Get the best source browser out there.
- xtt – time tracking built for the add & twitter inclined.
- GitNub – OS X GUI for tracking git logs.
4 Comments
very tricky.
There are roughly two different kinds of comments in source code: API documentation and clarifications of difficult to read code.
When you’re developing code with a public API it makes sense to document it. Keeping the API documentation close to the code has proven to be a good idea so it ends up in comments. There is no real good reason to use this kind of documentation when you’re not developing code intended to be reused often by a lot of people.
API documentation can get in the way of refactoring, but that is just the price you will have to pay. Good documentation doesn’t come for free.
In most cases you can write code in Ruby that is pretty easy to read if you choose good names. In some cases additional comments are needed to clarify the code, for instance when you’ve optimized a slow method with a strange syntactic trick.
I guess those are the two reasons to put comments in code. Clients might think otherwise but they hired you to solve a problem for them. Would they argue with a heart surgeon on the correct way to perform a bypass?
@manfred – this is the same pair of comment categories Neal identifies in his post, but his answer for API docs is that API docs in comments has all the disadvantages of comments, with the added disadvantage that most “street-smart” coders won’t even bother reading the API docs until after they’ve looked at the tests/specs. Neal’s answer is use tests and specs as your only docs.
I think of comments like a banana. A ripe banana doesn’t have much of a smell. An overripe banana has a strong smell, and a rotten banana stinks like hell. Comments are OK if you delete them before you finish, but the longer you leave them around, the worse they stink up the place.
Plenty of people disagree, I’m sure including some ENTPers, but I’m definitely anti-comment.
@george – you saw what I did there. ;-)
Привет, я думала что это совсем не так происходит:)
Мой блог: http://magazin-vyazanie.blog.ru/
Make your voice heard
Sorry, but comments are closed for this item.