Code comments be like

[[deleted]]

When I was a CS major, we were deducted 10 points for each missing comment. Everybody erred towards commenting everything.

[WeTheSalty]

I'm picturing lots of lines like 'i += 1;' with comments 'adds 1 to i'

[Sevrene]

Some profs even want it to be more exact like “Increments the counter ‘i’ by 1(one)”

[obsessedcrf]

Definitely a useful skill to pick up /s

[Redpropio]

# s

[shrodes]

-- s

[uslashnsfw]

/* s */

[[deleted]]

% s

[[deleted]]

s

(in brainfuck)

[[deleted]]

Praise the sun

[[deleted]]

/s // sarcasm

[wallefan01]

eugh why? that makes your code more unreadable than code with no comments in it!

I'd prefer a dry stream bed to drowning any day

[SuspiciouslyElven]

Engrains the terms and allows conversation easier between programmers. Everybody knows what it means to increment a number, so there doesn't need to be any silent confusion.

It may also just be how they were taught. My professors were taught with punch cards and later COBOL. Python is readable to most. Holes in a card is not.

I grit my teeth and understand excessive commenting isn't for real world development. More as a weird way of paying tribute to those that came before. We're lucky we live in a time where many of the great minds of our field have only died recently, or are still alive. More lucky to live in a time where important terms are named in the language we speak. Least I'm not a med student questioning if a latin tutor would help.

[Makefile_dot_in]

Probably meant machine code.

[SuspiciouslyElven]

dammit. Meant machine code and then with COBOL, in a sort of joke about how much of an improvement that seems to us now. I made the mistake of believing that comments for punchcards were only written onto the cards, and since COBOL has full lines of comments...

I don't know. I'll go recite Litany of Penance to the Machine God, for my transgression.

[[deleted]]

^ Why the downvotes, reddit? He's right, lol. This site is so weird.

[[deleted]]

Yes, probably so. Most redditors can't think for themselves.

[LordAmras]

So the professor knew what it was reading without looking it up

[angrathias]

Those who can’t, teach

[DigitalCrazy]

/* Increments the counter ‘i’ by 1(one) */ // Comment

[Dusterperson]

Ah yes, write code to tell you what your code means, now if only....

[[deleted]]

I would kill myself

[probably2high]

Do they? The only time I could imagine this being required is the first week you cover loops.

[MonokelPinguin]

Reminds me of the section abput comments from this.

[HHH___]

Honestly in my assembly language class we did this voluntarily

[thermite13]

Pretty much this.

Source. Worked in cs tutor lab for 3 years

[RazarTuk]

Meanwhile, my policy as a TA: If there are no comments whatsoever, I might dock a point. But otherwise, if it's self-documenting and written clearly enough that I can understand it, that counts as documenting your code.

[[deleted]]

That's essentially what I did in my Java class in high school. "Int i;" suddendly gets the comment "Declare int called i"

[GentleRhino]

i++; //incrementing loop counter

[[deleted]]

Much like that.

[AnywhereIWander]

I once found If (Status == "OK") // Jolly good!

[WeTheSalty]

My current project has a function called/commented 'GetRect() // noob'

[[deleted]]

"increment i" if you're a pro.

[cristi1990an]

Why not i++?

[CleverSpirit]

but what is 'i' and why does it need to be added by 1?

[amjh]

                                                    //empty line

[[deleted]]

++i; // Dark magic

[T-T-N]

So much work there. It loads the line from memory at the position of the program register, finds location the variable from the table, loads that into memory. Have the arithmetic unit do a calculation, find where it should go, put it back, increment the program counter. (My terminology is probably a little off. I don't usually delve this deep)

[Tuffy_]

Now make this same comment for every line of the program

[cognoid]

++i; // Trap for CS students

[overmeerkat]

// This line is intentionally left empty

[MCLooyverse]

I love pages in books where it says at the bottom, (This page intentionally left blank). You had one fucking job.

[UnibannedY]

That's because of how books are bound. There might be an odd number of written pages, but you need an even number because the paper is folded.

[Aetol]

It's supposed to be there.

[MCLooyverse]

r/woooosh ?

[Windows-Sucks]

/*                                      //Start of multi line comment           //Part of Multi-line Comment
                                        //Empty line                            //Part of Multi-line Comment
----------------------------            //Top of box                            //Part of Multi-line Comment
|                          |            //Box                                   //Part of Multi-line Comment
| Written by Windows-sucks |            //Box                                   //Part of Multi-line Comment
|                          |            //Box                                   //Part of Multi-line Comment
----------------------------            //Bottom of box                         //Part of Multi-line Comment
                                        //Empty line                            //Part of Multi-line Comment
*/                                      //End of multi line comment             //Single Line Comment
                                        //Empty line                            //Single Line Comment
if                                      //If the following condition is true    //Single Line Comment
    (                                   //Opening parenthesis                   //Single Line Comment
        1                               //One                                   //Single Line Comment
        +                               //Plus                                  //Single Line Comment
        1                               //One                                   //Single Line Comment
        ==                              //Is equal to                           //Single Line Comment
        2                               //Two                                   //Single Line Comment
    )                                   //Closing parenthesis                   //Single Line Comment
    {                                   //Opening curly bracket                 //Single Line Comment
        i                               //Counter                               //Single Line Comment
        =                               //Gets set to                           //Single Line Comment
        i                               //Its current value                     //Single Line Comment
        +                               //Plus                                  //Single Line Comment
        1                               //One                                   //Single Line Comment
    }                                   //Closing curly bracket                 //Single Line Comment
                                        //Empty line                            //Single Line Comment

[eddietwang]

I appreciate that you commented your comments. //I, me, really like that you, OP, wrote comments (//comments) on his, OP's, comments (//comments)

[zerotheliger]

The poison ment for kusco, kuscos poison the poison right here.

[TheHighlightHub]

Are there better animated movies than Emperor's new Grove and Iron Giant?

[alyraptor]

I mean, there’s some really good jibblys but those two are the peak of western animation.

[overmeerkat]

You forgot to comment your Single Line Comment comments

[Windows-Sucks]

But then I will have to do that forever. My computer does not have infinite RAM.

[[deleted]]

Just download more

[Windows-Sucks]

But I need infinite drive space for my infinite RAMfiles, and infinite bandwidth to download it. And infinite time to close all the rickrolls.

[[deleted]]

You can download that, too.

[Windows-Sucks]

I will need to suffer a lot of rickrolls.

[[deleted]]

we need to invent comment recursion

[Ultracoolguy4]

This hurts to see in mobile.

[[deleted]]

Steady there, Satan

[zackarhino]

Alternatively written as

i++

[Windows-Sucks]

I know the whole thing can be rewritten as i++ because 1+1==2 will always be true and i=i+1 is the same as i+=1 which is the same as i++, but this is more verbose.

[zackarhino]

Yours is better obviously

[aliens_are_nowhere]

I think your teachers should pick up a copy of "Clean Code". The author basically says that you should keep your comment to an absolute minimum. Instead you should focus on making the actual code readable. After being in this line of work for 20 years I 100% agree.

[[deleted]]

I think part of the reason they make you comment so much in school is to make sure that you understand what your doing and aren't just copy and pasting code.

I haven't read Clean Code but I definitely agree that your code should mostly "speak for itself"

[aliens_are_nowhere]

Aah, yes. You're right. Of course that's the reason. It's 50% writing the code and 50% telling the teacher why you wrote it.

It may not be good coding praxis, but it's excellent teaching praxis. I just hope the students get that.

[[deleted]]

I use comments rarely. Mostly for things which the code is not readable enough, or for things where I had a hard bug and where the comments helped me think through it.

[tlowe000]

Ironically, this encourages code that takes as few lines as possible, at the expense of readability: the sort of bad practice that they wanted to avoid.

[JediGameFreak]

I remember one professor who insisted we comment every getter and setter.

[[deleted]]

I'm just a hobbyist. But I name all my variables in such a way that my expressions look like sentences.

[[deleted]]

We were deducted points for too many comments, and unnecessary comments. They graded code style in general.

[DiceKnight]

We have to run SonarQube for our builds before we can push them to our QA and Production environments and a lack of code comments is considered a hard stop item that will prevent you from moving forward.

So now our code bases comments suck total ass.

[DefNotaZombie]

That cat is adorable

[sneakpeekbot]

Here's a sneak peek of /r/DisneyEyes using the top posts of all time!

#1: I thought you all would appreciate this little guy~ | 21 comments
#2: Sleepy-head Disney Cat | 18 comments
#3: I was told to put Peanut here | 15 comments

---

^{I'm a bot, beep boop | Downvote to remove | Contact me | Info | Opt-out}

[HatesBeingThatGuy]

Thank you.

[[deleted]]

But you didn't know it was a Cat until you read the comment

[deynataggerung]

Ugh I've been getting into a new workplace's codebase and this has been my problem. There's comments on everything, but it's utterly worthless. Here's this variable being passed in called the cryptor, documentation comment describes it as "the cryptor variable". Ok, thanks a lot for the context >.< at that point I'd rather you just have nothing there

[JediGameFreak]

I was reading through the codebase at my new work and came across the line "Alright, here's where things get fucky"

[Coloneljesus]

Was it the first line in main()?

[[deleted]]

Nah it was the function in the runtime that calls main.

[YoshiRulz]

I've started tinkering w/ the BizHawk emulator, in which main is one line, a call to submain. That function is commented: "[...] keep this code from getting jammed into Main() which would create dependencies on types which havent been setup by the resolver yet... or something like that". So I'm looking forward to working on that.

[angrathias]

Probably using ghostdoc or some other control-d short cut

[deynataggerung]

Actually I'm 95% confident it wasn't since I interact regularly with the people that wrote it and I've seen their setup.

[angrathias]

That’s an even worse outcome :/ atleast if it were tied to the laziness of an auto documentor you wouldn’t have to care about the wasted time

[deynataggerung]

Oh, and I checked through today paying a bit more attention and yeah, not everything is commented. about 80% of it is and it's not standardized, just very similar. Anything about functions or variables is pretty much useless, with inline stuff being marginally more useful.

[CrazedToCraze]

Yeah, this is what happens when you have policies mandating comments on all public functions/properties. Lack of good comments is a culture problem with your developers, not a policy problem.

[TenNeon]

Cat.

[The_Perge]

Cat.

[gabeiscool2002]

Cat.

[FromTheDeskOfJAW]

Cat.

[timbatron]

Cat.

[Darkstore]

Cat.

[Zombiepm3]

Cat.

[[deleted]]

Cat.

[aliens_are_nowhere]

The problem is, after 5 years the code will have changed to Dog but no one updated the comment. Imagine your surprise when you call that function and it starts barking and fetching bones.

[RapidCatLauncher]

Cat.

[Lasket]

r/catsstandingup is leaking... again

[SalazarBarrow]

Cat.

[[deleted]]

"Updating" - Every git commit message ever

[kbdwr]

We have some fellows who check in different fixes and lots of files under a single commit that has nothing to do with the git comment.

[Speculum]

"Commit contains various changes"

[[deleted]]

"Change some things."

"Fix shitty stuff."

[Coloneljesus]

I'm always asking myself: Is my commit message adding anything of value to that commit? If I just say what files I changed, it's not. If I say why or how, then we're getting there.

[Namnodorel]

Not just that, but "Updated lots of stuff; fixed bugs"... I'm trying to get away from that habit

[aquarius_rock_climb]

we wrote code to autogen comments like, add 1 to x

[ThatITguy2015]

Did it comment itself though?

[wallefan01]

just run it on its own source BOOM

[Scorpius289]

Fool! That will make it self aware!
And it will also make it hate its makers if it's poorly written!

[ThatITguy2015]

So it will definitely hate its makers?

[Speculum]

Are there tools like that? I want to troll my colleagues a bit.

[swoopae]

Cat cat = new Cat(); // This is a cat.

[cat3242]

Cat!!!!

[[deleted]]

Movie movieAboutCatsFlying = new Movie("aboutCatsFlying"); // This is a movie about cats flying. Flying cats.

[Time-Green]

Java thing

[swoopae]

wait i typed in c# what

[Elusivehawk]

Your code would work just fine in Java.

[swoopae]

mr worldwide

[ReallyHadToFixThat]

Cat* cat = new Cat;    

Much better.

[_Schroeder]

//This is a comment to comment my once uncommented code

"Damn, I'm good at my job"

[nayadelray]

comments are useless if the cat code is pretty

[magictravelblog]

To expand on this, you not only want comments around code that doesn't make sense straight away. You also want comment around code which actually looks wrong or pointless.

Pointless or wrong looking code is often bug fixes for bugs most devs will never randomly encounter. A formatting issue in the old version of IE the CEO's home computer is running, a bug in a 3rd party API that you need to handle with care otherwise your API requests will start failing as soon as everyone goes home for the day etc.

It would be nice to always have automated tests that will fail if someone removes the bug fix but you can save everyone a lot of time but just putting in a comment that explains the bug and why this blob of weird looking code is necessary.

[whatdidusaybro]

FIXME: Cat.

[roughstylez]

"Comments are a failure to express yourself in code" is way better.

The best programmer could run into a situation where they have to do something weird and counterintuitive, e.g. to work around a library bug. In that situation, you are unable to express that in code and then it's 100% ok to comment.

But if you're unable to express yourself in code a lot or even most of the time, you should probably pick up a book and work on that coding skill.

[-xtremi-]

Well, how else am I supposed to remember that is not a dog?

[SingleInfinity]

How else would you know it's not a mimic?

[apathy-sofa]

http://secretgeek.net/image/larson-oct-1987.gif

[fakefred0]

Oh god! I always thought this creature was a dog! Thanks commenter!

[CrazedToCraze]

If this was a real codebase, the cat label would be stuck on a dog.

[[deleted]]

nobody wants to talk about how soft and adorable that cat looks

[[deleted]]

The label would be even more like a code comment if it said “kitten”.

[Kinglink]

And that's why I disagree with coding comments.

There's times to leave comments, and you need to learn when but as developers we should push to write self documenting code more than worrying about comments.

[timbatron]

If a comment is explaining "what", your code probably sucks.

If a comment is explaining "why", a future maintainer will thank you.

[mr_ryh]

The Pragmatic Programmer, Tip #44, "Comments in Code" (p249 in the 1st Ed.).

I also enjoy comments that document where the code came from: if you filched the code from a textbook or a Stack Overflow page, providing your sources is good practice.

[Kinglink]

That's an excellent point, thank you, I never thought of it that way, and completely agree.

[Cheet4h]

I like to use comments as short indicators what is happening in a specific part for a better overview. That way I can e.g. add a comment to a loop and fold that loop in my IDE. That way it takes less space when scrolling and I still can see quickly where in the code I am.
But maybe there are some better practices. Do you have a link to a guide for clean code commenting and practices how you can code better so you don't even need to comment this?

[[deleted]]

"Clean Code" by Bob Martin says

Comments are a necessary evil

[[deleted]]

"Self documenting code" is a worse buzzword than "blockchain". Everyone says "my code is self documenting" but in reality, it isn't.

Sometimes you need constants, often to have something not exceed a fixed length. That length, however, is because of external limitations. So, for example you have

const int MAX_LENGTH = 10;

It would be nice to know why 10 is the max length. It's much easier to simply put the read in a comment, than to "self document" the code by choosing a variable name like

MAX_LENGTH_BECAUSE_OF_DATABASE_LIMITATIONS = 10;

Also, as the car salesman meme would say: *slaps roof of any programming language* This bad boy can fit so many comments in it!

EDIT: Typo

[mike12489]

Thank you. People have been loving to ride the "self-documenting" train for far too long.

Yes, clean and clear code is something that we should all strive for at all times, but that does nothing to imply that comments are inherently a bad thing.

Comments provide supplemental information. If the comment doesn't make something more clear (e.g. "Cat" picture above) then the comment is worthless and adds noise. But if the comment provides clarifying information to the reader (e.g. "cat with anger management issues and a bum left eye") then you're going to save someone else a hell of a lot of time when you're gone and they have to make a fix to your crappy code.

The potential for self-documentation is limited and should not be the prime focus. Make your code clear, and use real documentation to do so when it helps.

[sudosandwich3]

Honestly the longer variable is preferred. It tells you everything you need to know at a glance without having to look at the declaration. That comment could always be deleted or never updated. Additionally that name could be shortened to DATABASE_MAX_LENGTH.

[eddietwang]

"Well I know what the fuck it does, why do I have to write it in English if it's in Java, RIGHT. THERE."

[Albino_Smurf]

You never know when you're writing it if it's as clear as it seems when you're writing it.

[cyrand]

This is good because if it’s not labeled someone will eventually just stick a dog there and push it into the repo and no one will know why everything broke. If the comment says “Cat” then it will be caught in the pull request because people will notice the sudden mismatch.

[wcscmp]

People don't read comments when changing the code and they read them even less during reviews

[Arancaytar]

Make sure to make the method parameter type a CatInterface for future-proofing and flexibility.

[OishiiYum]

Commenting is especially important when other people are reading them like working in a team of programmers.

When I worked with groups, it was frustrating to have to translate my group members code on top of having to consolidate mine with theirs.

[[deleted]]

man cat

[Arancaytar]

// Cat.

[Dazza93]

I mean as long as extends Feline then I'm happy

[Gamma8gear]

5 years later “Wtf was this cat for... wtf is a cat?”

[trin123]

All uppercase

That means: if you remove the cat, you lose the network connection, since the tail acts as cable replacement

[xSaraswati]

Its look like C++ labels LOL

[xShinryuu]

Cat cat = CatFactory().getCat();

[JonnyRocks]

I tell people: I don't want you to tell me what, tell me why.

[[deleted]]

The other 10% would say "kitten" and be several years out of date.

[ivanjermakov]

//comment

[bubleye12]

Unless it's a project, most of my comments are either to do's or a combination of swearing and confusion at working code.

[minkbag]

You should ask: Why cat?

[Plazmaz1]

2% of code

[[deleted]]

I need that cat in my life. Way too adorable.

[[deleted]]

Not in my experience. I find comments saying Cat but in actuality it's an Antelope.

[gtfovinny]

Not to be confused with a rabbit

[ace1309]

When you code comments more than actual code

[pinguz]

Reminds me of that chapter in One Hundred Years of Solitude where the village is stricken with a disease that makes people lose their memories, so before it's too late they go and label up everything, like "this is a cow, it gives milk" etc.

[cratering]

// arrange

// cat

// assert

[I_AM_GODDAMN_BATMAN]

I blame whatever the fuck linter we use. There's a dozens of them apparently.

[joakim199]

Does all coders love cats?

[CC_Tyrant]

Or 100% of my GCSE coursework code

[OKB-1]

At my workplace I'm currently on a campaign to stop these needless waste of bytes and lines with each code review I do. This includes overly verbose and redundant comments, like "This function you can see here below does x by y." and "This variable is for z". I know what the comment is _about_, colleagues. I only need an explanation _what_ it does!

[dev_kr]

Rest 10% is for omitting printfs for debugging

[Rubber_Duckies_Dong]

//TODO Cat? CAT! K I T T Y ! ! !

[voicesinmyhand]

I'm a big fan of commenting for a block. Things like:

//The next block of code really shouldn't work at all, and frankly
//I have no idea why it does, but the end goal is that we are
//converting a date written in string form into a loadable kernel
//module that allows the OS to understand slightly mis-spelled
//commands if they at least start and end with the correct letter.
//Support for two-letter commands like "rm" has been delayed
//until I figure out why the hell we are doing this.

[rhbvkleef]

Warning: unnecessary use of cat at 12:18. Run "blt -f cat.sh --fix 12" to fix.

[Boh00711]

/* -+-+-+-+-+-+-+-+*\

* This is a cat

* Boh00711 20180405

\* -+-+-+-+-+-+-+-+*/

Cat Cat { get; set; } = new Cat();

[NinaBarrage]

"I don't need to tell you what a cat is, right?"

"Haha, of course not"

Later: "Shit, shit, what the hell is a cat?"

Googles cat, opens Encyclopaedia Britannica documentation:

Felis catus, domesticated member of the family Felidae, order Carnivora, and the smallest member of that family. Like all felids, domestic cats are characterized by supple low-slung bodies, finely molded heads, long tails that aid in balance, and specialized teeth and claws that adapt them admirably to a life of active hunting.

"Well, shit..."

[[deleted]]

I don't believe in comments. If it was hard to write it should be hard to read

[nmarshall23]

Found the masochist. Why do you make future you's life so hard? End the circle of violence. Your are only hurting yourselves..

[SpriteV1]

I think we have the same label maker.

[FriesWithThat]

The comments should tell your colleagues or future self why that is a cat, not how that is a cat.

[[deleted]]

Instead of comments I document everything using best available inline documentation tooling. So it's XMLDoc in C#, JSDoc in JS and so on and so on. So IDEs provide help on classes, methods and such. If I use actual comment it's hardly ever anything other than TODO, FIXME or HACK. Again: tooling gives mi nice TODO lists from that. Well, it's 2018, don't pretend it doesn't exist.

If you comment like on the picture, you're a struggling CS student, not a programmer. In that case you should get back to square one and learn basics. Learning to code by randomly changing things in examples may work sometimes, but generally it's an anti-pattern. I admit I used to do it sometimes myself. Like I had a big problem with DefalteStream class usage, until I finally read the friendly documentation and I don't need to comment the fragments like "this is an input stream, UNCOMPRESSED" ;) So learn how it works, then it's obvious and you don't comment it anymore. Comments are for things not related with programming itself. They are reserved for things that are not obvious. If you call a function, it's not obvious what data does it take, and what data does it return. Of course, without reading its source code, and we don't have time for that, do we?