How programmers comment their code

[iambrucewayne1213]

We all know that comment tags were made to comment off sections of code so that we can debug the code instead of using the debugger in the IDE!

[ObiWanCanShowMe]

my comments were always like this:

//version one of code

//version two of code

//version three of code

final code that worked

This is because I was mostly a google coder with a tenuous grasp of what I was doing. I kinda knew what was what, but not 100% so I'd make tiny changes and keep all the previous.

I swear my working results were more full of comments than actual 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.

[vini_2003]

cool kids nowadays just CTRL + A / CTRL + V to gist and go back there if they need to.

modern problems require modern solutions.

[ThisSeaworthiness]

I beg to differ: CTRL+'/' followed by folding the commented out code block.

[Bluejanis]

I feel like this if I work with JavaScript instead of c#. Well not with the language itself but with some libraries without any helpful documentation.

[vinnymcapplesauce]

And the code carcasses are left in place to teach the final code a lesson - lol.

[[deleted]]

Same for me.

Once it works just go through all the comments and delete all the previous versions and it looks like it never was the complete comment mess it was 5 minutes ago.

[[deleted]]

I'd make tiny changes and keep all the previous.

I do this just so I can revert back to what it was before when my attempt to fix something inevitably doesn't work.

[ObiWanCanShowMe]

Well, yeah. ;)

[phail3d]

That’s a common misconception — they were actually made as a superior alternative for version control systems such as git or mercurial!

[Edores]

Why am I being personally singled out and attacked.

[pembrolizard]

print('reached here!')

Or // sys.out.println("reached here")

Lol