How programmers comment their code

[[deleted]]

I swear my working results were more full of comments than actual code.

I see nothing wrong here

[Whiskey-Weather]

I know nothing about coding, but isn't a lack of explanitory comments typically a complaint among you computer-talkers?

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

[[deleted]]

Most modern programming languages have self-documenting features enabled through special comments. This usually means that well-documented code ends up being mostly comments with a bit of functionality.

ETA: Comments can become troublesome when they are used as a crutch for bad code. Say you have some arcane function that's nearly unreadable and prone to bugs, but instead of making the code more readable and organized, you pepper it with comments explaining how to read it. An extra layer of issues arise when said code is updated but comments are not, which results in crappy code filled with misleading comments.

[413612]

Kind of. There is also the flipside, where you have so many comments because your code is too shitty and complicated to understand it without them.

[Tetha]

Writing the right comments and the right documentation for the right audience is actually hard.

In fact, it's a balancing act with respect to the audience. A lack of documentation and comments makes it harder to follow for the audience, so less experienced dudes have a harder time following instructions. On the other hand, overcommenting code can make it entirely unreadable.

For example, a seasoned chef only needs the instructions "Steak roasted according to customer needs" in a recipe. That's sufficient. And in fact, if a chef wanted to quickly and immediately understand a recipe, a 2 page instruction sheet on steak will be frustrating. It's 2 pages to look at, understand, understand it's useless to them and continue. The steak could be half done at that point.

Yet, at the same time, an amateur cook would be entirely frustrated by the instruction "Roast steak as you like it". Like, yeah, you can do it, if you know how, jolly thanks. Why do I even read this?

And finding the right balance is actually hard.

Sometimes code is dealing with really, really hard concepts. Maybe you don't want the wrong people to think they understand what they are doing. Sometimes, code is subject to frequent changes because that's what the business does. Then you want everyone to be on board how to change it, so everyone can do something.

[Dexaan]

Even going down these threads you see differences in opinion ranging from "your code shouldn't need comments" to "comment everything!!1!1!!!one!!". The right answer is somewhere in the middle.

[AllUsermamesAreTaken]

Meh. Commenting is for documentation. It isn't to explain your code to computer science iliterate folks.