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 custo...
For further actions, you may consider blocking this person and/or reporting abuse
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.
Good article.
However, an important point with the comments to me is they have to explain what, but most important, why. If the code is nicely coded, you can easily understand what the code does, but the most important thing is to understand why. Why the developer tests this variable ? Why the developer uses this function to do this and not another one ?
There is a good example, in my point of view, in your example. The fourth comment is : "Check if the team has reached the limit or not". It's explain what the code does, but not why. If you want understand why the developer has written this test, you have to read the code until reading the returns message : "Daily log limit reached", so the comment is not that good to me. A good comment would be : "Check if the team has reached the limit or not, cause we have a daily log limit, due to small-size disks"
But we totally agree on the important point of this article, comments are a critical issue and an important part of a developer's job.
Great article! We actually have a commenting standard at my company, MousePaw Media: Commenting Showing Intent