A comment is worth leaving. I’ve come round to thinking there isn’t one that explains what the code does. If you need a sentence to say what a block is for, the block is telling the wrong story. Rename the function. The comment disappears because nothing needed explaining.

People hear when I say this that I want no comments at all. A comment that explains why, or cites the paper the algorithm came from, or records the incident that made this branch exist, is doing work the code cannot do. That kind of note belongs next to the module and ages fine. The one I want gone is the running narration, the line above the loop that says what the loop does. Those rot first, because the code underneath them changes and the sentence above it doesn’t.

This is not a style preference. A comment is a second copy of the meaning. The code does what it does and the comment says what it used to do. The reader now has to decide which one to believe. That’s worse than no explanation at all, because the wrong one is right there in the same file looking authoritative.

Agents have made me firmer on it rather than softer. A developer reading a vague function works the intent out from everything around it. An agent takes the function name and the comment at face value and builds on whichever it read last, so a lazy name becomes the vocabulary for the next twenty files. The code is the meaning because the code is what gets copied.

If the meaning isn’t obvious, the move is always the same: rename the function, split it, improve the parameter names. Look again and look harder before you reach for the comment.

The full write-up is at https://prickles.org/tenet/self-documenting-code/F5

  • copygirl@lemmy.blahaj.zone
    24·
    3 days ago

    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.

    • thingsiplay@lemmy.ml
      3·
      3 days ago

      over-commenting things can be annoying

      Not only that, it can also be a wrong comment when forgotten to update them when changing the code. In such cases no comment is even better. So I do less comments than before nowadays, especially with Python. You also have to think who your target audience is (future you? teams of professional game devs? scientist without much programming knowledge? random online beginners?). Finding a middle ground is mostly impossible, so having the target audience in mind is important in my opinion.

      • dreamkeeper@literature.cafe
        3·
        2 days ago

        Imo it’s not that hard to fix. If someone changes code then you force them to update the associated comment as well. Don’t allow them to merge without updating the documentation.

        In regard to audience, I guess I’m lucky because only engineers will read our code and I suspect that’s true for most people. I wouldn’t concern myself with beginners tbh, unless there’s some reason you really need to. I think that’d lead to unnecessarily verbose comments that wouldn’t help anyone.

        I’d much rather have both “self-documenting” (which I don’t fully buy as a concept) and well-documented code at the same time.

        Self-documentation has many of the same problems people point out with comments anyway.

        • thingsiplay@lemmy.ml
          1·
          2 days ago

          The point of self-documenting is, that if you need to explain it in a comment, you probably should update the code to make it readable by its own. This is not meant to be the only way going forward. It’s just to have this in mind and try to do it whenever an opportunity you see. More a thumb of rule thing, rather than hard reality.

    • technocrit@lemmy.dbzer0.com
      3·
      3 days ago

      Agreed. I tend to write one-liners that I don’t want to re-parse myself later, much less force someone else to parse. A simple comment can be a major help and time saver for everybody.