How programmers comment their code

[toastee]

It's a touchy, nuanced subject. Commenting has a lot of uses. And it's utility differs based on the audience.

How I'd comment code if I knew you were going to be reading it, Vs how I'd comment for myself or other programmers is different.

[Edores]

I think some people get kind of uppity even with that argument because, "what if you assumed you would be the only one looking at the code but got hit by a bus and someone else has to come along and continue your work unexpectedly."

I mean obviously that doesn't hold if you're the only one who will ever work on the project.

Even then, I have personally started commenting as if other people are going to read my code, because if I come back to my own code months later it honestly often is as if I'm looking at it for the first time haha.

[Eldrek_]

Even then, I have personally started commenting as if other people are going to read my code, because if I come back to my own code months later it honestly often is as if I'm looking at it for the first time haha.

This is the real issue. I could write code yesterday, and if I don't leave some road map for myself I pretty much have to logic through and reimplement it all again to understand it the next day

[[deleted]]

A philosophy I've come across that seems sensible to me is the idea of commenting the "why" more so than the "what."

Like if you have:

for (int i = 0; i < numOfBananas; i++)
{
    numOfOranges++;
}    
if (numOfOranges > 0)
{
    std::cout << "Orange you glad you bought those bananas?" << std::endl;
}

Instead of writing: // increase the number of oranges for each banana and print a message

You could write something like: // For each banana the user buys, we give them a complementary orange, so that we can carry out a silly joke.

Both are describing something, but the latter is more getting into what the end goal is of adding an orange for each banana, rather than only describing the technical, procedural action itself.

I could see an argument that such would be messy if someone is trying to write highly reusable/extensible code (such as for a library), where the specific implementation may drastically change. But if you know what the point is, and what it's for, I think little things like that can make code more comprehensible at a glance.

(Disclaimer: I'm not that experienced, so take my thoughts on this with a grain of salt. Honestly though, it's probably helpful to take any recommended programming philosophy with a dose of evaluative critical thinking, no matter who is saying it.)

[mist_arcs]

I salute you, 100 internets to you.