The value in it is that you’re backing your words. You keep making empty claims, and then choosing not to back them up, which serves to suggest that your words have no merit. You have the opportunity to prove otherwise, or not.
Indeed. Just like a function that depends on another function becomes out of date once this is changed.
What kind of objection is that?
Just developers convene to interact with code in certain ways, and when they don’t things don’t work, comments, being part of the code, also thrive or not depending on the environment where the code lives.
These two are even more true in the case of Python.
This is comically false. You are joking, right?
1 Like
I don’t think we are going to see eye-to-eye here. I am not going to further participate here.
Value lives in context. In this case, it doesn’t. It has no value to me, to be explaining more to someone who has already chosen to be obtuse about a very narrow use for comments in code. Given some time, when you forget about, it is likely to see you internet warring about the complete opposite position. I pass.
It’s not comically false, he’s not joking, and there are a LOT of people out there who agree with him.
The autocomment that comes to my mind is subtle semantics or pre- and
post- conditions or invariants of various parts of the code.
Here I’m thinking:
- here’s an important if-statement buried in a largeish loop body whose
omission or breakage badly changes the outcome - here’s a loop - notice that it preserves some invariant during the
loop - preconditions: here’s a piece of code - it will fail (exceptions
(easy) or nonsense (harder to qualify)) if given values outside
certain domains - postconditions: this piece of code ensures that X is true at the end
If there was software which could examine portion of the code, perhaps
starting with the smallest pieces and assembling streadily larger
semantic descriptions), maybe it could do things like emit some pre/post
conditions or observe invariants. And then document them.
How often have we tried to understand some piece of code and wished for
commentry? Particularly of the internals? Even of our own code written
long ago?
I know I come back to my own code and occasionally add explainatory
comments to important things in the middle of some large chunk. Those
comments are, alas, often the WHY but often they also say “this is to
ensure that X remains true” and that latter may be mechanically
deducable.
As with humans, later it may become possible to recognise common things
from the conditions required/preserved/ensured and come up with some
succinct additional labelling like “this code downcases a string” as the
leading comment.
That’s where I’d imagine a mechanical autocommenter could bring value.
Turning the LLM thing on its head (since to my mind, LLMs are basicly
recognising statistical patterns and/or making things with the same
statistical patterns on the generation side, hence their ability to
produce plausible nonsense), on the recognition side maybe an LLM saying
“this looks like code to do X” could either weight the actualy semantic
analysis or let the analysis falsify the LLM summary/guess.
This is all just specualtion.
Cheers,
Cameron Simpson cs@cskk.id.au
I concur, and find this intuitive.
I often write inline comments in outline form, where the comments explain in plain English what a group of statements is doing. Yes, what the code is doing. Especially when modifying an existing code base with large under-documented functions.
By summarizing one or more statements into a single comment, I no longer have to mentally parse the code every time I read it, and the next person who has to modify a function they’ve never seen before will have jumping off points for their own work. The information in those statements is condensed into a smaller, easier to digest space.
You can absolutely annotate one or more statements in a way that expresses their what in a way that is easier to read and comprehend when scanning a code base and I think that adds value.
I find the arguments about generated comments becoming out of date irrelevant. This is equally true of any comment you write yourself regardless of its content. I can write an explanatory “why” comment and then the products business requirements change, part of the code is modified and the comment becomes inaccurate. So what. Update the comments, it doesn’t matter if they’re generated or not.
2 Likes
That would be interesting, but like many other suggestions in this thread, should not be saved with the code - it’s analysis, a sidebar, but not comments (or, in this case, assertions). I’m also dubious that an automated tool would be able to distinguish interesting pre/postconditions from the utterly boring ones.
(And if someone actually wants to pursue this, it wouldn’t start with a survey on comments, it would be an attempt to analyze pre/postconditions of code. So it’d be quite separate from this thread.)
And that’s not how research publications work - you must measure something unless you’re writing a literature review on a topic. Quantifying the subjective quality of a comment generator means yes, publishing a survey on comment quality, because you need human participants for their subjective judgements and you need a baseline.
Further OP mentioned his tool was based on formal methods - analyzing pre and post conditions is exactly what formal methods is about.
You can’t do quantitative research on automated analysis of pre-conditions and post-conditions without reviewing the barely-related concept of code comments?
Now we are probably talking past each other so I won’t say much more here. I’m trying to point out how OP is already doing exactly what you just said is a better alternative. You think they started with a survey? They’ve already spent multiple years learning supporting information, and integrated formal methods into a prototype, and has likely done broad reviews of the existing literature on their chosen topic. This isn’t the first thing they’ve done, and all the work they’ve already done is likely one reason they feel it’s unnecessary to prove their foundation to you - it must seem rather intuitive after soaking in the literature for months, and their adviser already approved their topic anyway.
Ask about being on the board for OPs dissertation defense if their thesis is so controversial. 
1 Like
You seem to have some personal definition of what a code comment is that is based on the content of the text, which is not how this word is generally used. Moreover you seem to use your personal definition of comments to get mad at me for claims I never made in the first place. And if you define comment to be something that cannot be generated by an algorithm, then by definition it would be impossible to generate by an algorithm.
I also don’t know what kind of information that is not in the code you are talking about. I can think of many different things I can write about that’s not directly in the code, but about the code which are going to be completely useless to anyone reading them. There is also a lot that can be inferred from the code that isn’t directly in the code. And if you have a good coding style and name your functions and variables properly, that can also give an additional context that will help in generating very good comments.
In addition the definition of a useful comment is non-trivial and there isn’t a consensus on what it actually is. Can you actually write a full definition of what comment is useful that I can take, look at some code and say - yes, this classifies as a useful comment? I mean other than “it needs to say why the code is there” and “it needs to tell something that’s not in the code itself”? These by themselves aren’t enough.
Yes, yes I have. Did you see what I asked it to do? I literally asked it to generate comments for a line that says “nonlocal popup”. Can you write a comment for this line what will be non-redundant and carry additional useful information? Moreover the fact that a system generates comments like these is not an indicator that it’s bad. Any kind of algorithm like this must start by producing something trivial and working on trivial things. Because if you cannot even generate comments for easy trivial lines, you wouldn’t be able to do anything useful at all for any code. That’s why it’s sponsored research project and not a product to sell.
This is also totally something that a human would write sometimes. I can tell you because I have more than a million open source projects that worth a few terabytes of source code from which I extracted comments and conducted a detailed statistical analysis on what developers actually write in the comments. And let me tell you that quite a lot of time they either write nothing or something trivial that can be inferred from code, or even something auto generated by an IDE, like the template stubs.
And if you give this output to anyone who has never seen this function before and ask them to understand it, those comments will help significantly with understanding what is happening in the code without spending an hour reading every little line and making sure you totally get it.
1 Like
No, which is why, in the original code, there was no comment there. You managed to autogenerate useless comments. Not every line needs a comment.
I did ask it to produce a line by line comments, literally, I just pasted that snippet in and said “give me line by line comments”. It makes sense that it produces redundant and trivial comments for trivial lines of code when explicitly asked for it, no? It doesn’t show that it’s bad in any way. And the resulting comments are not actually wrong and they assist in understanding the code quite well.
And some of the generated comments are actually close to what you wrote, which was my point. You can just remove redundant ones if you actually use this in your code or you can play with prompt to get something of better quality.
1 Like
I am not arguing that every line needs a comment. I am saying that a system that actually generates any sort of code descriptions or comments must by necessity produce those trivial comments or it just won’t work. I gave it a specific task which it did. I didn’t ask it to find good places for comments and such. Moreover, it is actually arguable if the comments you find unneeded are actually unneeded. Give your code to someone else that have never seen your project before, one with your comments and one with ChatGPT and ask them which ones are better. Otherwise we have a situation where you say “I write perfect comments and if anyone disagrees, they are plain wrong”.
We asked you to show that a computer could generate useful comments. You showed that a computer can generate useless comments, and now you say that that’s okay, because that’s what you asked for.
Then why did you post it in response to that request?
Two of them barely came towards the mark, and that’s because those were the two most trivial of the comments that I’d written. So you’ve shown that some human-written comments aren’t very useful. In that code block, there were far more than two comments, and you completely missed making any of the useful ones.
I’m done. This discussion is not worth carrying on with. Clearly your idea of code commenting is COMPLETELY different from mine, and from everyone that I’ve ever collaborated with (other than students, and I already said that what you’re doing might be of value to complete novices, but not as code comments).
1 Like
Can you define what information it is, other than saying “it must not be in the code”? Because there quite a lot you can actually infer from the code. Of course it would be impossible to infer something that like requirements or relationship between objects or fields if it’s implemented.
Something similar to this is actually already possible. I am also planing to extend my system in the future to write out things like these.
Also, if you have ~20 minutes, please take the survey, I would really appreciate it.
I really don’t know what to tell you. You seem to blame me for every comment generation system in existence. I promise you I didn’t make all of them. You also seem to have your own definition of what a source comment is, which is not how it generally understood.
Your problem seem to be with the overloaded use of “comment”, and if using a different terminology will make you happy, sure. I am making a system that generates descriptions of what the code does, as well as summaries of methods and classes and api documentation. It is unclear at the moment complete scope this project will take in the future, but my goal is to guarantee that the produced text will correspond to what the code actually does and can be used for education and documentation.
Here. This is what my project is, so hopefully the misunderstandings with regards to what a source comment is cleared by this.
Top result for “good code comments” agrees with mine and @Rosuav position that comments should not be duplicating the code: Best practices for writing code comments - Stack Overflow
So do most of the other top results. Please, tell me, what is the definition of code comments you are using? Or do you think the examples from the survey follow these best practices?
You are saying “that’s how academy uses the term code comments”. Maybe academy has a warped understanding of that term? It definitely doesn’t match the usage of day-to-day developers in industry.