Do you let the code speak for itself? Or do you comment until the cows come home?
At Mobile Jazz we develop mobile apps and websites for our customers. We’re committed to delivering high quality software, and for us that means paying attention right down to the smallest detail.
A timeless hot topic among developers is commenting on the code. Even within our team we hold animated internal discussions on this: Some people rarely comment on their code, while others like to throw in a bucketload.
One of the main purposes of adding comments is to aid future work. In our case this is particularly crucial, as it enables us to work on different projects at the same time or work on a project every X months only.
Let’s look at a real example from some code we inherited from one of our developers. We came across a problem that should have been a breeze to solve. But, because of a poorly constructed comment, it quickly turned into a real headache.
Here’s the screenshot:
As you can see, the comment makes it clear that there’s a custom library jar, but this doesn’t really help us. Here’s why:
- Usually, comments are placed before the code it refers to, not after. In this case, the comment refers to volley.jar library. So that’s a mistake from the developer; the whole team should be consistent when adding comments to the code.
- The description doesn't provide any information, it just says we are using a custom jar for some unknown reason. It would be much better if we knew why those changes were needed.
- It doesn't point out the location of the custom library’s source code, or how to build it.
As you can see, comments are important. Usually developers don't pay too much attention to the comments because, to them, what they’re working on is obvious.
Imagine, however, that this particular developer leaves the company. So, too, do the rest of the team over a 2-year period. Now there’s no-one in the company that understands the comment, and when a new developer needs to delve back into the code—whoops, there’s no way of knowing what’s going on. This is exactly what happened in this example.
Also, you should always document any change you make to an existing library and keep the code of the modified version. Then, you can add a link to the code and the document of changes, via the comment itself. If you are using a public library available in GitHub, it’s a good idea to create a branch of the original library and keep the modified version in your GitHub account.
Do too many cooks spoil the broth? Absolutely not.
It’s always better to have too many comments than none at all. In my case, for example, I work on a lot of different projects and languages at the same time, so for me having comments on the code helps massively when it comes to quickly understanding what's going on.
Let’s take a look at another example, this time of code with quality comments.
The following screenshot contains some GO code from Bugfender. Even if you don't understand GO and don't know anything about Bugfender you can easily follow what's happening the code:
Yes, most of the comments might look redundant as the code is quite clean and clear, but having the comments in plain text allows anyone to understand what the function is doing in just a couple of seconds. There’s no need to understand GO or the models in the product. It makes it so much easier if you then want to delve deeper into a particular area of the code.
Now, take a look at the following screenshot of some previous code we inherited from a client:
Yes, there are some comments in the code, but it’s really hard to understand what the code is doing even with the comments as they don’t provide enough information.
The more complex the code, the more comments it should have.
Conclusion
At Bugfender and Mobile Jazz, we take code quality very seriously. We always ensure our projects are written with clean, clear code that can be easily understood and transferred to our clients.
Here's our blueprint for writing comments:
- Comments are key. Write them!
- Think about the future of the code/app. You might not be around or perhaps you’re not going to revisit it for a couple of years. Will you be able to understand the code in one year from now?
- When you write comments, imagine reading them through the eyes of another developer seeing them for the first time. Do they make sense?
- Document/save any changes you make to a library. A must if you’re building a project.
Do you have any commenting rules in your company? Share them with us!
Top comments (18)
I subscribe to the 'prefer code to comments' and use Extract Method to pull out - and name - those blocks headed up by a comment.
Certainly, the last example isn't suffering because it has no comment s. They would just be band-aid for a too big, too complex single function. Get the Refactoring axe to it!
Personally, I consider the Bugfender example a code smell, perhaps even an anti-pattern. Write the code clearly. If you need, add a function with a clear name. Then you do not need to repeat what the code does in a comment, because, reality shows us, that the code will change, while the comments will not. So, at best, the comments are redundant, at worst, they will be incorrect.
It's a good idea to comment on the WHY. "Why do we take the first three characters from this stream here?" "Why does this method add +1 here?" etc. These comments are great, they are important. But not comments about the WHAT. The code itself should make absolutely clear what it is doing, making any comment about that useless. Comment the intent.
Also, sorry, but comparing a few lines of a simple method to a indenting orgy isn't fair and the indenting orgy would not be better with more comments - it would be worse. The way to make that code actually clear is to refactor it, adding a lot of methods - but NOT to add more comments into already horrible code.
First, write readable code.
Use comments as a last resort where the code cannot be any clearer as it is.
Remember that comments, like documentation, need to be maintained. A misleading comment is more harmful than a poorly written code.
Any discussion of comments has to distinguish between comments on function/methods/classes/etc. and inline comments. Inline comments are often code smells -- you should consider whether the code can be written more clearly or extracted into another function that explains the intent of the code.
Adding more lines of comments is overhead, like adding more lines of code. You have to be sure that the cost (of maintaining them and having to read them) is worth the benefit they provide. Don't say things in comments that the code could say or already does say.
This is why we use source control. Why do we need to save a copy of the unmoified code? In Visual Studio and Git, with Code Lens you can actually see for each function who was the last person to modify it, you can see the commit history for the file and see all the versions of the file and diff it with the version you are currently working on. So why would I need to take a copy of the code I am working on and post it to GitHub? Also many devs work at companies where doing something like that is a violation of company policy. So they would get in trouble for following that advice.
The main problem is that we only have the binary version of the library, so there's no way to fix bugs on it. We know it's based on an open source library that has already fixed some bugs but as we don't know what was changed in our version we cannot use any new version of it.
So are you commenting the work arrounds you have put in place to get the library working? That is a valid use of code comments, but in your article I don't remember that you mention that. I would be very careful using such a library since it has known bugs and could easily become a security problem.
But still does not answer the question of why do you need to take the orginal source code and put into a public repo in GitHub and then put a link in a code comment in the code you modify. Why do you think that is needed? With good source control tools you can look back at version of the code that was modified that you want to look at. I have never needed to do this nor have I have seen others do it. In fact if I did this at work with out approval I could lose my job.
I haven't said to upload it to GitHub, but put it somewhere. It can be a zip file in GDrive or on a private repo in Bitbucket. You are right that publishing something to Github without permission can be dangerous.
The problem we have is that there's a modified library in the project and we don't know how to update it or change it.
It's definitely true that comments are important. On average, I think I have to add more comments to my code than I do most of the time. So I'm on the same page here.
However, I think that you could have chosen a better example to compare commented/not-commented code. I mean the commented example is coded nicely. The not/bad-commented example is a very complex function that no one should have to work with ...
Comments should not try to tell you WHAT you are doing (checking if we have an app token). This can easily be done by creating a short method 'hasSessionAppToken'. The amount of information stays the same. This can be done with all comments in the example starting with 'Create'. Why isn't that method called 'CreateSessionFromAPIDate'?
This kind of commenting leaves to things like
// returns name of person
public String getName(){return this.name}
So please... Do not write comments that explain me WHAT you are doing, except it cannot be done in an obvious way. Do write comments on WHY you did things this or that way.
Overall I liked this article. It only touches points I've come across before (I would have liked to see at least one reference to one of the many existing articles on the topic), but the specific examples offer an opportunity for re-evaluating my understanding.
But this bothered me:
Be careful with absolutes. This is certainly not true. Comments add nothing to simple, straight-forward, self-documenting code.
E.g., Christian Dohnert's example:
Peter, I'm the author of the article.
Maybe you are right about the example, but it just happened that I was working on both codes and I felt it could be a really good example of how comments bring value to an already nice code and how a bad code can be even worse without comments.
If your code "requires" a lot of comments, it's bad. If your code is bad, it should not make it past a pull request.
I'd MUCH rather have clean, well-written code without distracting comments than bad code full of comments.
I'm a consultant, and the project I'm currently on is chock full of really convoluted, unclear, hacky code. It's also littered with comments. Comments that are often times outright wrong, rarely written coherently/legibly, and rarely provide value. Many of them are on the line AFTER the line they describe, too.
Rather than demanding that your team fills their sub-optimal code with comments, why not mentor and educate them on writing better code in the first place? I've written a blog post called "Comments Are a Code Smell" that covers a lot of my feelings/thought on comments in code: programming-is-easy.com/comments-a...
In my experience, even well-written code can be improved by comments and I'm pretty sure that if the code is well-written the comments will be where they should be and provide the information they should provide. And you are absolutely right, a bad comment can be a nightmare.
I spent a lot of time trying to figure out why we were using a custom library to find out that I was looking at the wrong library.
Of course, that teaching people to write better is a lot better, but that's something for another post.
Your personal experience with bad comments is exactly why I use comments only as a last resort. Once I write a comment I try to think of how I can express my intent in code with out the comment and look at ways to remove them through refactoring. With modern refactoring tools it is pretty easy to extract a method and name it with the comment you just wrote. So why not encourage that instead of writing comments that can easily go out sync or move and mislead people and waste time because the comment was wrong?
Bad code as in the example is about 1000x more important to fix than the comments. Comments feels like bike-shedding. I discourage comments and discussion of comments because I find most times effort is best spent on getting rid of bad code, of which there is always plenty to get rid of. Write fluent APIs, write good tests, and most developers -- even those who don't know the language or the problem (as is the case with the Go example) -- will figure it out in 10s or less.