When I was a newbie, the "self documenting code" screed made sense to me, but with experience I've come to learn the type of person that is likely to latch onto it and advocate for it writes the least maintainable code.

Don't make 80 character function names or change to structure of code to something worse to try to make it self documenting. Don't write comments that are already obvious from the code. Don't be shy about writing comments otherwise. Do update comments and ask people to update comments in PR feedback.

Most of all, fuck writing less maintainable code to try to satisfy LLM agents.

Self documenting code goes only so far. At some point, you want to explain why you do it, not what you do. And commenting blocks of code will be necessary to have good documentation. Sometimes having too long function and variable names can make the code less readable, so that is not always a good idea. For an LLM it is excellent, but if a human reads the code, then its different.

So don't forget writing / changing code is not just for reading by agents (LLMs) and code reviewer tools. You can satisfy them, but it might cost you readability for humans. I also like having code searchable through grep (line wise thinking, also good for git changes) or search and replace (variable names in example). These are interactive tools as I call them, and are meant for used and read by humans too.

There is lot of consideration when it comes to make code readable and usable in long term.

Comments can help people see what the code is doing at a glance, without having to figure out what a particular function call is doing in the context where it's being called. Sometimes, you're just skimming, because you're looking for something specific. Perhaps it helps you when searching for keywords? Here, I'll include an example: Yesterday I wrote a little Godot mod loader, part of which is tweaking the project export to .zip up mods separately instead of including them in the main game.

# Ensure the output `mods/` directory exists.
DirAccess.make_dir_recursive_absolute(output_mods_path)

# Clear out old mods from the output `mods/` directory.
for name in DirAccess.get_files_at(output_mods_path):
	DirAccess.remove_absolute(output_mods_path + "/" + name)

Now, admittedly, Godot's naming of its built-in functions isn't helping. But yeah, you can take a couple seconds to understand what the function call does, or you can read the comment and immediately have context for the code after it. I don't think throwing these 3 lines into their own 2 extra functions would help anyone. Then again, maybe these are 50% "why" comments and 50% "what" comments.

On the other hand, here's a larger comment that is needed to explain why that bit of code exists:

# Resources reference additional files that may be compressed or otherwise pre-processed,
# which are exported to `.godot/` instead of `mods/` and are listed in the `.import` file.
var import_file_path := file_path + ".import"
if FileAccess.file_exists(import_file_path):
	var config := ConfigFile.new()
	config.load(import_file_path)
	for dep_file_path in config.get_value("deps", "dest_files", []):
		_zip_file(zip, dep_file_path)

I understand that over-commenting things can be annoying, I understand that it's good to encourage people to name symbols appropriately and to split things into functions that in some way act as good documentation on its own. But if you go too far, you end up with tons of methods that you have to jump around in the source code to figure things out, and that could pull you out of the flow too.

Commenting for the sake of commenting? No. AI slop comments? Heck no.

Commenting because it helps you internalize how something works, or helps you remember? Go for it! Commenting because you feel like it'll help the next person understand your code? Please don't shy away. I'd rather have a couple more unnecessary comments than too few with a spaghetti of nicely-named function calls.

There is no such thing as self documenting code. In any project the code can only ever tell half the story, the rest must be documented. Even then, I don’t always want to have to go back and figure out what each part does. There is a reason basically all code repos also have built in wikis.

Sometimes the 'why' is important.

You should have learned this in school or from your mentor.

cites the paper the algorithm came from

Having done this, I usually put a comment referencing which step of the algorithm I'm on along with whatever the "title" of that step is (the primary action from it, like "collect flex items into flex lines" from CSS Flexbox Level 1 step 9.3.5). Sometimes, the following line of code is that entire step and is self-explanatory, but I still feel like the comment explains why that line exists by referencing the algorithm directly.

Indeed. Don't comment "what", only comment "why". If you've written code that looks like a mistake but is there for a reason - poor algorithm, not idiomatic, etc. - then the proper "comment" is a unit test that exercises the business logic behind it, but a one-liner to stop someone from "fixing" it is maybe polite too. Don't write an essay for private functions; rename them so they're obvious.

Just keep in mind that method names can also get stale and you have to be extra careful there because, when reading the parent method, you only see the method name without the code alongside it.

Yeah, I always tell people the fundamental problem with comments is that they're only visible in one place. Method/variable name, log outputs, error messages, docstrings all show up in at least two places, which makes them more valuable in general, but also makes it more likely for them to be read+updated.

How would you do this with SQL?

And sure, we can carefully choose the names of our SQL stored procedures and input arguments. But inside of a procedure where actions take place and statements are made to achieve those? How easy is it, in your experience, do split off sections into their own procedure and rework their name?

I have never gotten anywhere with coworkers arguing this. They write the dumbest comments and resist feedback in PRs. Now with LLMs we're adding a bunch of unit tests that are about half comments. I cannot begin to express how useless these comments are. No one is going to read 15 paragraphs to understand a slop unit test. If that shit breaks it's not going to be obvious why. Between the verbosity and writing style, these comments are some of the least grokable shit I've seen in my career. My coworkers have basically let me know that my feedback is noted but they disagree.

Docstrings are fine as well. I mean for generating something like an API documentation with Sphinx. Other than that, yes. Everyone should learn this in programming school right at the start. Get into the habit. Name things properly. Write it in a way the code is expressive in what it does and how it does it.