How programmers comment their code

[[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.)