Asking an LLM to add comments is actually pretty much the worst thing you can do. Comments aren’t meant to be documentation and LLMs have a habit of writing documentation in the comments. Documentation is supposed to be in the documentation, not in the code.
LLMs are often trained on things like tutorials, where super obvious statements are commented to allow people to learn and follow along. In actual code you absolutely do not do this, obvious statements should be obvious by themselves. At best it’s extra work to read and maintain the comments for obvious statements, at worst they are incorrect and misleading. I’ve worked on systems where the comments and the code weren’t in line with each other and it was a continual guess if the comment is the way it was supposed to work, or if the code is correct and the comment wrong.
So when do you actually add comments? That’s actually very hard, something people argue about all the time and a bit of an art form to get right. For example if I have some sort of complex calculation, but it’s based on a well known algorithm, I might comment the name of that algorithm. That way I can recognize it myself right away and someone that doesn’t know it can look it up right away.
Another good indicator for comments are magic numbers. It’s often smart to put these in constants, so you can at least name them, but a small little comment to indicate why it’s there and the source can be nice. Or when there is a calculation and there’s a +1 for example in there somewhere, one might ask why the +1, then a little comment is nice to explain why.
Comments should also serve like a spidey sense for developers. Whenever you are writing comments or have the urge to add some comments somewhere, it might be an indicator the code is messy and needs to be refactored. Comments should be short and to the point, whenever you start writing sentences, either start writing documentation or look at the code why it’s required to explain so much and how to fix that.
Another good use for comments is to warn away instincts for future devs. For example in a system I worked on there is a large amount of code that seems like it’s duplicate. So a new dev might look at it and see a good place to start refactoring and remove the duplicated code. However the duplication was intentional for performance reasons, so a little comment saying the dupe is intentional is a good idea.
I’ve also seen comments used to describe function signatures, although most modern languages have official ways of doing that these days. These also might border on documentation, so I’d be careful with that.
LLMs also have a habit of writing down responses to prompts in the comments. For example the LLM might have written some code, you say: Hey that’s wrong, we shouldn’t set x to y, we should set it to z. And the LLM writes a comment like // X now set to Z as requested. These kinds of comments make no sense to people reading the code in the future.
Keep in mind comments are there to make it easier for the next guy to work on the code, and often that next guy is you. So getting it right is important and hard, but very much worth while. What I like to do is write code one day and then go back and read it the next day or a few days later. And not the commit, with the diff and the description, the actual files beginning to end. When I think something is weird or stands out, I’ll go back and edit the code and perhaps add comments.
IMHO LLMs are terrible at writing code, it’s often full of mistakes and oversights, but one of the worst parts is the comments. I can tell code was AI generated right away by the comments and those comments being present are a good indicator the “dev” didn’t bother to actually read and correct the code.
this is among the most important comment types that exist imo
it may not seem like it but 20 years and 5million lines later when shit behaves odd because of some non standard code practice this type of comment is a life saver
Excellent comment and I fully agree with almost everything. Just one tiny nitpick:
For example if I have some sort of complex calculation, but it’s based on a well known algorithm, I might comment the name of that algorithm.
Unless you really need this complex calculation to be inline (e.g. for performance reasons) it would be better to move it into a function or method and include the algorithm in the name instead of adding a comment.
Very good! Your spidey senses are working perfectly. Hey I want to comment this calculation, why don’t I move it into a function so the name can explain what it does. Good call!
Sometimes the algorithm is inlined for performance, sometimes it’s a class with a bunch of functions that as a whole is primarily based on an algorithm, so comments might make sense in those cases. Most of the times it’s a library, so the name of the library kinda gives it away and hopefully has good documentation as well.
I disagree that comments are an indication of messy code. The purpose of comments are to 1) translate low level concepts into higher ones for improved readability and 2) to maintain information in the design process that can’t be represented by the code itself.
Obviously I don’t have to comment mathematical operations, but it makes sense to comment the algebra of how I derived an equation and it’s use in the code. Now, I could refactor that section of code into a function in order to give it a name, but that would make it more difficult to read as the programmer would then have to find the definition of that function somewhere else in the file. It is objectively more spaghetti-like to pull out single-use code into a function rather than just label the block of code with a comment.
Asking an LLM to add comments is actually pretty much the worst thing you can do. Comments aren’t meant to be documentation and LLMs have a habit of writing documentation in the comments. Documentation is supposed to be in the documentation, not in the code. LLMs are often trained on things like tutorials, where super obvious statements are commented to allow people to learn and follow along. In actual code you absolutely do not do this, obvious statements should be obvious by themselves. At best it’s extra work to read and maintain the comments for obvious statements, at worst they are incorrect and misleading. I’ve worked on systems where the comments and the code weren’t in line with each other and it was a continual guess if the comment is the way it was supposed to work, or if the code is correct and the comment wrong.
So when do you actually add comments? That’s actually very hard, something people argue about all the time and a bit of an art form to get right. For example if I have some sort of complex calculation, but it’s based on a well known algorithm, I might comment the name of that algorithm. That way I can recognize it myself right away and someone that doesn’t know it can look it up right away. Another good indicator for comments are magic numbers. It’s often smart to put these in constants, so you can at least name them, but a small little comment to indicate why it’s there and the source can be nice. Or when there is a calculation and there’s a +1 for example in there somewhere, one might ask why the +1, then a little comment is nice to explain why.
Comments should also serve like a spidey sense for developers. Whenever you are writing comments or have the urge to add some comments somewhere, it might be an indicator the code is messy and needs to be refactored. Comments should be short and to the point, whenever you start writing sentences, either start writing documentation or look at the code why it’s required to explain so much and how to fix that.
Another good use for comments is to warn away instincts for future devs. For example in a system I worked on there is a large amount of code that seems like it’s duplicate. So a new dev might look at it and see a good place to start refactoring and remove the duplicated code. However the duplication was intentional for performance reasons, so a little comment saying the dupe is intentional is a good idea.
I’ve also seen comments used to describe function signatures, although most modern languages have official ways of doing that these days. These also might border on documentation, so I’d be careful with that.
LLMs also have a habit of writing down responses to prompts in the comments. For example the LLM might have written some code, you say: Hey that’s wrong, we shouldn’t set x to y, we should set it to z. And the LLM writes a comment like // X now set to Z as requested. These kinds of comments make no sense to people reading the code in the future.
Keep in mind comments are there to make it easier for the next guy to work on the code, and often that next guy is you. So getting it right is important and hard, but very much worth while. What I like to do is write code one day and then go back and read it the next day or a few days later. And not the commit, with the diff and the description, the actual files beginning to end. When I think something is weird or stands out, I’ll go back and edit the code and perhaps add comments.
IMHO LLMs are terrible at writing code, it’s often full of mistakes and oversights, but one of the worst parts is the comments. I can tell code was AI generated right away by the comments and those comments being present are a good indicator the “dev” didn’t bother to actually read and correct the code.
There’s also the class of comments that explain strange business decisions.
# Product guy said to return January 1st if the user doesn't have a birthday on recordKind of arbitrary but someone with decision making power decreed it.
this is among the most important comment types that exist imo
it may not seem like it but 20 years and 5million lines later when shit behaves odd because of some non standard code practice this type of comment is a life saver
Here, under protest is this code. Every time the user doesn’t have a birthday, we return January 1st. Do we really mean that?
Some tooling generates documentation from comments. Like rustdoc or LDoc.
I’ll be honest, I mostly skimmed through your comment. Sorry if it’s something you touch upon later on.
They’re doing more than math.
Excellent comment and I fully agree with almost everything. Just one tiny nitpick:
Unless you really need this complex calculation to be inline (e.g. for performance reasons) it would be better to move it into a function or method and include the algorithm in the name instead of adding a comment.
Very good! Your spidey senses are working perfectly. Hey I want to comment this calculation, why don’t I move it into a function so the name can explain what it does. Good call!
Sometimes the algorithm is inlined for performance, sometimes it’s a class with a bunch of functions that as a whole is primarily based on an algorithm, so comments might make sense in those cases. Most of the times it’s a library, so the name of the library kinda gives it away and hopefully has good documentation as well.
i want it in a function
fully include the pre implementation long hand in comments and the book / expert reference
the number of times i’ve found longer algos not doing as advertised is scary
improperly used statistical algos given the data sets and hand waving results are so common
gee i wonder why testing shows no improvement
I disagree that comments are an indication of messy code. The purpose of comments are to 1) translate low level concepts into higher ones for improved readability and 2) to maintain information in the design process that can’t be represented by the code itself.
Obviously I don’t have to comment mathematical operations, but it makes sense to comment the algebra of how I derived an equation and it’s use in the code. Now, I could refactor that section of code into a function in order to give it a name, but that would make it more difficult to read as the programmer would then have to find the definition of that function somewhere else in the file. It is objectively more spaghetti-like to pull out single-use code into a function rather than just label the block of code with a comment.