// TODO Add comments
Except realistically the standards around commenting are going to change dramatically over the next decade because of generative AI.
I’ve been toying with selecting ‘comments’ as my language of choice for my next hobby project to see if pseudocode and comments can lead to a language agnostic project that can reliably be reproduced in multiple languages.
As the tech gets better, more and more of the job is going to be writing comments about what the code should do as opposed to documenting what it does do.
Just write your code, so that you (almost) don’t need comments (i.e. simple to read). The problems with (most) comments won’t be solved by AI.
(in-code) comments only make sense for me in roughly these scenarios:
- complex piece of math possibly from a paper (e.g. a ref to the paper where it is explained)
- function doc, here AI may really help at some time (right now, I’ll rather write it myself, AI represents this post very well in an even more verbose and literate way than the typical junior dev…)
The problems with comments are explained well IMHO here: https://www.youtube.com/watch?v=Bf7vDBBOBUA
This couples intentions to the code which in my example would be dynamic.
That’s going to be a bad time.
My point is that the conventions that used to be good for the past 50 years of development are likely going to change as tooling does.
Programming is effectively about managing complexity.
Yes, the abstraction of a development language being the layer at which you encode intention rather than in comments is better when humans are reading and writing the code itself.
But how many projects have historically run into problems when a decade earlier they chose a language that years later is stagnating in tooling or integrations versus another pick?
Imagine if the development work had been done exclusively in pseudocode and comments guiding generative AI writing in language A. How much easier might porting everything to language B end up being?
Language agnostic development may be quite viable within a year or so.
And just as you could write software in binary, letting a compiler do that and working with an abstracted layer is more valuable in time and cost.
I’m saying that the language is becoming something which software can effectively abstract, so moving the focus yet another layer up will likely be more valuable than clinging to increasingly obsolete paradigms.
Language agnostic development may be quite viable within a year or so.
I doubt that very much, GPT4 (to my knowledge still the best LLM) is far from being there. As (my) initial hype is overcome, I have basically stopped using it because I have to “help” it too much (and it got really worse over time…) so that I spent more time to get any usable results from it, instead of just writing the goddamn code myself. There has to be a very large step in progress, that this is anywhere feasible (maybe that’s true for some “boilerplate” react UI code though). You have to have in mind, that you should still review all the code which takes a good chunk of the time (especially if it’s full with issues as it is with LLMs). Often I go over it and think yes, this is ok, and then I check it out in more detail and find a lot of issues that cost me more time compared to writing the code myself in the first place.
I have actually fed GPT4 a lot of natural language instructions to write code, and it was kind of a disaster, I have to try that again with more code instructions, as I think it’s better to just provide an LLM the code directly, if it will really get smart enough it will understand the intentions of the code without comments (as it has seen a lot of code).
Context size is also a bigger issue, the LLM just doesn’t have as much overview over the code and the relevant details (I need to try out the 32k GPT4 model though and feed it more code of the architecture, this may help, but is obviously a lot of work…)
Same for humans, if your code is really too complex, you can likely simplify it, such that humans can read it without comments.
If not, it falls for me in the first category I’ve listed (complex math or similar). And then of course comments make sense for a complex piece of code that may need more context.
I would only add comments otherwise for edgecases and ideas (e.g. TODO).
For the rest a good API doc (javadoc, rustdoc etc.) is more than enough (if it’s clear what a function should do and the function is written in a modular way, it should be easy to read the code IMHO.
Really if you need comments, think about the code first, is it the simplest approach? Can I make it more readable? I feel like I have written a lot of “unreadable” (or too complex) code in my junior years…
What otherwise makes sense for me is a high level description of the architecture.
Here is an alternative Piped link(s): https://piped.video/watch?v=Bf7vDBBOBUA
Piped is a privacy-respecting open-source alternative frontend to YouTube.
I’m open-source, check me out at GitHub.
Code never lies. Comments sometimes do.
Oh, you ain’t never encountered a boolean named the fucking opposite of what it does?
Better: I’ve encountered a pair of booleans that appear to be exact opposites but aren’t. To protect the guilty I’ve changed the words: isOpen and isClosed, when one is true the other is false and vice versa, EXCEPT that while something can’t be both open and closed at the same time, it is possible for something to be not open and not closed.
A lot of this comes from professors wanting comments in assinments and grade on arbitrary levels of if it exists.
I had one class where the instructor would give a vuage “not enough comments” that I did comments like this on every fuction and loop out of spite.
Code documentation is like sex, when it’s good it’s great, and when it’s not good…it’s still better then no documentation.
I disagree. When comments are essentially just a rephrasing of the class/method name or arguments it is not helpful and anything that is not helpful is cluttering up the code and making it harder to quickly see what the code is doing. I’d rather have no comments than comments like that.
I reserve comments for explaining why a section of code is needed or explaining how a complex algorithm works.
i = 0; // Set i to 0 is pointless.
if (last_output_vertex[i] == bounds[i]->length - 1) contibuting_bounds[i] = NULL; // stop outputting a bound if the entire bound has been output is helpful.
I think even the second comment is not that helpful.
Just use (boolean) variables that phrase what your comment would explain, often more concise and better to read IMO. Also if the logic is more complex compose multiple named (boolean) variables. I think comments seldom make any sense at all (function doc is a one of the rare cases, mostly for the user of the library in the IDE).
Comments can also be useful for explaining what the code is intended to do when debugging.
“Hey this function says it should return the number of apples, but looks like someone, not saying who, but someone had a brain fart and typed oranges in one variable. Who wrote this code anyway?”
-Last edited by JonEFive in 2021-
Past me sucks.
And if you’re male.
Edit: FFS does no one realize that women experience sex differently from men? Bad sex with an oblivious partner can be downright painful for a woman. The same is typically not true for men. My point was not that women don’t have sex or that they don’t enjoy sex. My point is that they don’t experience it the same way as men.
