Comments in code are quite often a code smell. Let’s see what is suboptimal about comments and talk about some strategies to avoid them.
deleted by creator
Having spent many times having to walk Technical Architects through code, explaining what it does, or trying to introduce new coders to software development, I comment line by line. It’s not just experienced coders that have to look at your code. I will never not do this.
This is a little bit of a case in point of why documentation should not be written by the teacher. It should be written by the student. The student takes no knowledge for granted and so will only repeat themselves insofar as they need to. The teacher will either repeat themselves consistently, or just leave massive gaps due to their preexisting knowledge. Even though it wouldn’t be practical for a coder to have some student document their code, I feel like this still illustrates the point. Also it means you have to constantly put yourselves in the shoes of some future student, which seems like a good practice anyway.
I think this is also in line with my article, since not being able to put yourself into somebody else’s shoes (or even in yourself future’s ones) is the reason for so much bad comments. But adding a comment to every single line cannot be the solution either, at least not in a higher programming language.
I guess one could understand why the author believes this if his experience has been (mostly) limited to poorly commented code.
I have also seen well commented code, but in this article I concentrate on the bad ones. Are you saying you have never seen a bad code comment?
Comments should be used when it’s hard to convey the intent using only code. For example, maybe there’s some unintuitive border case that must handled. Then it could be useful to add some explanation with a comment.
I also like to add comments when I find some clever solution/workaround on the web. For example, some stack overflow answer or Wikipedia page of some algorithm.
Totally agree, that’s why I also mentioned this in the article.
Very often good code that is self-explanatory does not need any comments at all and if it does, the comment should describe why it has been implemented this way instead of just repeating what the code already says.
Comments are also useful when something appears to be wrong but there’s a good reason why it’s like that
// Don’t remove this comment! Production will break if removed
While I agree with some of the premises here, I personally disagree that comments are even mostly a problem (a code smell). IMO they’re just as often bad as code is. A developer in a rush, or simply not taking enough care in their work, can produce both bad code and bad comments.
Perhaps someone who is trying to take care can do more harm in the comments area, when they should be perhaps looking at writing self documenting code, but in my experience they usually go hand in hand.
I use quite a lot of comments in my code and I wouldn’t regard it as code smell or even messy. I often use comments to logically separate more complex sections of functionality… or discussing how it works and why it’s necessary to exist in the first place. Code can’t always tell you why it’s there…
I also use docblocks in some libraries, even though types are available, as the published package benefits from having an API document published alongside it. The comments there facilitate its construction.
I know this article wasn’t bashing every use of comments in code but I feel like it didn’t account for all the positive uses of them either. Teaching developers that a language feature is just mostly bad is irresponsible - we should be encouraging good comment use alongside clear code.
The code is the “what”, the comments are the “why”. It’s the mantra I use when making them. So in a fundamental way, they never repeat themselves.
I agree with almost all of what you say, but the thing IME is that in most cases people learn to comment a lot, which results in comments that feel like they’ve been done just for the sake of it, which is one of the main problems IMO. It’s not like “just add a comment, it won’t hurt”, since comments can be immensely misleading and literally take a lot of time until figuring out that the comment was wrong if you trust the wrong ones.
I also agree that this tends to be worse with bad code, which also is not surprising. Sometimes it feels to me like people think they can fix bad code with some comments, and I think that is far from being true.
I also admit that especially the title of the article might be a bit provocative, but giving the general positive sentiment of comments I think this is called for. Sometimes you have to exaggerate a bit to get some attention. I don’t like click-baiting either, but unfortunately it works ;-)
DRY is not an inviolable rule. Some of the most tedious code to debug is because somebody thinks puppies will die if they write the same pair of lines in two different places.
I think this is one of the most common misconceptions about DRY. Just because you have two times the same line in your code base it is not automatically a violation of DRY. If you compare if a number is bigger than 18 it is definitely not a good idea to extract that part if you are comparing the hour of the day once and the age the other time. In that case it would even be bad to create an abstration, and it would not be a violation of DRY. And I agree that something like this leads to code that is hard to maintain.
There were times I’ve done line-by-line commenting to reverse engineer code I’ve written in the past. Also very important in case of Assembly and similar problematic languages.
I’ve also done some line-by-line stuff to show how my engine is initialized, so people will understand why a given line is there and not just have to know what lines they must type in.
Yeah, comments are absolutely necessary in languages like assembly and gcode.
I give you that, but I am not talking about assembly languages, therefore the examples from my blogpost aren’t showing any :-)
deleted by creator
deleted by creator
