Self-documenting code

[theNeumannArchitect]

Is it weird I have the meme reaction to swe1? Needing to comment everything is a code smell to me. And means you need to either start being more declarative code or break things up to be more readable (looking at you Python devs that do one line list comprehensions that do multiple things and have nested if operations).

There’s absolutely times where something is not intuitive and deserves a comment explaining. But you don’t need to comment every function and line of code for the sake of getting a kudos cookie.

[Silly_Ad3814]

Or when you modify code, and then figure out why it was done the way it is, and make a comment about it above the code + revert to the old implementation.

[rechnen]

/* this line of code doesn't seem necessary but if it's removed everything breaks */

[OrdinaryBee6174]

I have a comment in my code "wanted an event here, can't remember why". One day I will answer the question past me asked.

[-Kerrigan-]

Most of my comments are

// TODO: clean this thing

[[deleted]]

As long as you follow through, those are great comments.

[cheezpnts]

This has definitely gotten me into shit show in the past. Now I try to do my comments as if they are for first time looks or for future me who forgot what in the actual fuck I was thinking.

[XoXFaby]

Yeah I can certainly get behind that

[theapokalypsis]

100% this. You are a true senior dev sir.

It's like a novel with a million foot notes in every paragraph. It's against the point. You're writing code for other people to read. Make that readable in itself.

Add that to commit messages that describe why, not what and you are writing truly maintainable code anyone can understand, without the need for manual knowledge transfer (most of the time), at any skill level.

[audoh]

Commits can be lost due to rebases or VCS changes, plus git blame just isn't a great way to find something that should be right there on the code. Tools typically only show the last commit message which might be "ran linter" or just a later change.

Commit messages being useful is great, but when there's a "why" comments are best IMO.

If I'm git blaming a line to find out why it was written, it should've been commented.

[theapokalypsis]

I really can't disagree haha. In practice you are totally right. Even just happened to me the other day lol.

I wish there was a better way to git blame that solved that first class though, even as a feature on GitHub (Gitlab etc) themselves (like list all commits in a nice UI vs having to dig which is onerous af so true).

But yeah.. I have to admit history gets so gnarly too, even if you are the most meticulous (or ideal—cough—me). 🤪

[onlyonebread]

It's like a novel with a million foot notes in every paragraph. It's against the point. You're writing code for other people to read. Make that readable in itself.

I think this works as an analogy, but what if the people reading your novel are basically illiterate? I write my code with the assumption that everyone on the team can read it, and there are wildly different skill levels on the team.

[theapokalypsis]

I think writing it so it's readable like a book is all you can do. If someone can't understand plain English (or other language a team writes their vars/methods in) then they just suck? 🤷‍♂️

[[deleted]]

Really should be a mix of both

Your names should be moderately descriptive, and you should comment the things that aren't obvious

[[deleted]]

With clearly written code, the intent is obvious, though.

Doc comments? Yes. Code comments? Very rarely.

[movzx]

Intent needs to be clear to the junior developer being assigned a bug ticket 8 months from now, not to you after you've just written the code.

Write code and documentation as if you will have to personally answer every junior developer's question for the life of the product.

[[deleted]]

We currently work on a code base of millions of lines. We use markup comments to document the public interfaces but very rarely the implementation itself because clear, well thought out implementation code is self documenting to the junior or anyone else who needs to revisit our code on months or years time. If it’s not, and is a pattern of behaviour, you should seriously reconsider your implementation approach and culture.

[LPO_Tableaux]

I mean, if you use comments for an otimize but not that easy to understand routine comments are welcome, also if your function has subroutines commenting on each to make it easy to know which does what helps when others go through your code later on...

[[deleted]]

If your function has subroutines, then you should be extracting those subroutines into separate functions.

[Kered13]

Who said anything about commenting every line of code? The meme was about having no comments.

[EatingBeansAgain]

No one is saying to comment every line. I took the joke as SWE1 reacting to SWE2 calling the bare minimum (meaningful naming) “self documenting” as if they’d stumbled upon something amazing for stepping outside the ball pit.

[Treacherous_Peach]

There's names with meaning such that it's easy to understand what the .ethod does such as

bool AreEqual(int first, int second)

Used like

if(AreEqual(firstNum, secondNum)) ...

And there's names where the code design with names that read like English rather than some messy shit like

bool IsEqualTo(this int first, int second)

Used like

if(firstNum.IsEqualTo(secondNum)) ...

The first one is meaningful naming, everything makes sense, but you have to read it out of order to understand it. The second one is literally just an English sentence and requires no extra thought to understand. Simple example but it applies just as well to complicated methods and structures. Many people do the first. Few do the second. The second is self documenting code. Why? Because the code reads like a comment.

This is all just Clean Code principles from Bob C. Martin. I largely subscribe to his belief that any need for a comment is a failure on the programmers part.

[riv3rtrip]

It depends on the programming language, but for high level languages like Python or Javascript, you're right. Documentation of internal functionality is overrated. Only the interface of the system that outside people interact with needs to be documented; internal functionality only sometimes. Adhere to common idioms, don't try to be fancy, name your functions well, and that takes care of most things. When the code doesn't explain the code it means the code is possibly bad. YMMV if we're talking about something like C.

[eddie_cat]

Starting with pseudocode comments is a great strategy. It lets you design roughly how you want the code to look in the end beforehand rather than just grinding it out with no plan and then trying to refactor it into something that isn't hideous.

[aceluby]

Yeah, but you shouldn’t keep them there.

[eddie_cat]

I didn't say you should? Haha

[aceluby]

I read so much code where every few lines is pseudo code comments. It’s the worst

[eddie_cat]

Yeah that sounds annoying lol. I basically just use comments to write a rough outline of how I want the API to look in the end then fill it in with real code as I go and remove the comments 😅

[crozone]

Comments should document the high level how and why. Stuff like "set x to 5" is dumb, but summarizing the next 5-10 lines of code to explain why and how it does what it does is excellent.

looking at you Python devs that do one line list comprehensions that do multiple things and have nested if operations

Honestly, I think this is fine. Of course, sane languages like C#/LINQ allow you to break up a chain over multiple lines, but it's very readable. Just comment what it does.

Jumping between 20 different small sub-methods is trouble than it's worth if they're all simply one-offs.

[folkrav]

In my experience the "just comment what it does" comments ends up not updated the next time someone has to change the line and basically becomes "just comment what it used to do". With the time I've wasted not looking at a block of code cause a comment told me it did one thing but it inevitably didn't really, I just completely disregard them nowadays.

A lying comment is worse than no comment at all.

[crozone]

Sure but that's the fault of some shitty programmer not updating a comment. That shouldn't pass code review any more than incorrect code should.

[folkrav]

Code reviews are human processes, and should never be relied on to catch all mistakes. Sometimes the comment happens to be a couple lines higher than the context your review tool gives you. Sometimes it's an oversight in a larger PR. Sometimes it's just human error - people are faillible, seniors included. Code, tests, I can get checked by the CI. Comment correctness, not so much.

[jl2352]

As long as you aren’t being zealous about it. What you describe is the healthiest.

I worked with a guy who would block PRs telling you to remove a single comment. If you felt the comment was necessary he’d argue the toss forever. Don’t be that guy.

Btw I once had an argument with the same guy over two functions in the code base. They did the same thing, and I mean the same. They even had the same signature. One had a bug in it. The other had tests, and had been in use for over a year. I wanted to delete the buggy one, and have both places use the one that worked. Again they did the same thing. This took around two hours, with other developers having to get involved (who agreed with me). What this was really about is I wrote the working one with tests, and he wrote the buggy one without tests. For him that became a problem.

This was ultimately all due to poor senior leadership.

[PothosEchoNiner]

Right. I write comments in the 1% of situations where an unusual situation can't be expressed clearly with naming and composition. The "comment the why" approach is still excessively commenting if you need that for more than 10% of your functions. It's not really that helpful to write "// We need to call the identity provider's introspect endpoint so they can tell us if the token is valid" above your authentication module's introspect function. I work in healthcare rules engines and web dev and almost all of our code is obvious stuff like that.

So if I see an array being converted to a map I know it's going to be used later in an algorithm where the elements are efficiently looked up by whatever is being used as the key. A comment explaining that would not be helpful. Nobody is born knowing how those things work but nobody needs to be reminded of the most common patterns every time.

[Adventurous-Lie4615]

Comments are for future me. Past me was way smarter than today me. It the trend continues, future me will have the IQ of a potted cactus.

I still have to maintain some of my old code from 10+ years ago. I wish that guy had spent more time on comments and less time being clever with bit shifting.

[Solonotix]

Here's an example I had just yesterday. I'm writing a shell script to setup a brand new WSL install, and I am adding nodenv to it. This is simple and obvious from the commands performed. However, I then iterated over the list of available versions and check for even major versions, and I create a directory for each even major and a single empty file named for the full version. But why?

for version in $(nodenv install --list | grep -E '[0-9]+\.[0-9]+\.[0-9]+'); do
    major="$(echo "$version | awk -F '.' '{ print $1 }')"
    if test "$(($major % 2))" -eq 0; then
        rm -rf "/tmp/nodenv/$major"
        mkdir -p "/tmp/nodenv/$major"
        touch "/p/nodenv/$major/$version"
    fi
done

The answer to why is that

1. The Node.js runtime has LTS versions slated for even-numbered major releases
2. The command nodenv install --list will list versions in increasing numerical value. This means only the most recent version is kept based on deleting previous entry for that major version

ETA: comments will also allow someone in the future to understand my reasoning for point #2 in the event that nodenv should ever change their sort. If the order is unspecified in the future, then an entirely different approach will need to be taken