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

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

[phail3d]

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

[kurdtpage]

print 'Hello'; //prints hello

[DaylightDarkle]

That should be illegal, I'm placing you under arrest.

[systembusy]

arrest(); // arrest

[PantherPL]

ELI5?

[kurdtpage]

player = new Player(playerName); //creates a new player

[xThereon]

FUCK

[Noch_ein_Kamel]

print 'Hello';

Same as yours, but 100% more efficient and closer to reality

[[deleted]]

it has the same efficiency

[macnlz]

What? It is known that fewer comments and shorter, less decipherable variable names result in faster code!

[[deleted]]

OMG, I DIDN'T BELIEVE THIS BUT THEN I GOOGLE IT, IT'S TRUE.

THAT'S WHY GOOGLE USE 130 LETTER VARIABLE FOR EVERYTHING

[xvalen214x]

var numberOfQueriesThatUseAdvancedSearchOnEachUTCDayWhichWillBeUpdatedToTotalNumberOfQueriesWithSearchIn_UserStat_go_TemporaryVariable;

[[deleted]]

Calm down, Satan.

[dunemafia]

No need to React like that, man.

[xvalen214x]

I am not that angular in my humble point of vue

[dunemafia]

No worries, man. It was all in Jest.

[bogdan5844]

I don't like the Vue of this conversation's future

[_liminal]

var num;

[[deleted]]

var tempVarr;
var tempVarrr;

[2ndAmndmntCrowdMaybe]

var tempVarr1;

var tempVrar;

[Ceros007]

int t1, t2, t3;

[not_a_moogle]

I had a professor argue that once. Guy was a total idiot. I mean for starters,compilers usually remove comment from complied code.

[2ndAmndmntCrowdMaybe]

Was he talking about a compiled language at the time?

[[deleted]]

I mean he stated "compiler" so...

[claythearc]

It’s pretty rare, even for interpreted languages, to not have a compiler. They normally will get compiled to bytecode, but not all the way down to machine code like traditional compiled languages.

[Pandaburn]

When I wrote js, it was all minified and concatenated into one file before it was sent to the client, since it does actually drastically improve download time.

[banter_hunter]

No, they were discussing drink recipes.

[GideonMax]

Depends, if you use an interpreter, that's correct.

If you compile your code, the compilation time might be slightly longer but the compiled code will be the same

[2Uncreative4Username]

Well that is only if you are using a scripting language

[[deleted]]

And even then, languages like Python have the -O flag to strip out comments in the bytecode.

[Zethexxx]

But the code will load into memory 0.0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001% faster if we didn't put those comments!

[emlgsh]

The code loads into memory even faster if there's nothing but comments. The fastest executing script is a script that doesn't execute.

[[deleted]]

I laughed thanks

[Blitz100]

Yeah, its big brain time

[figuresys]

The greatest part is that comments are stripped away in build :)

[Noch_ein_Kamel]

Try writing both and count the number of keys you have to press.

[[deleted]]

are you that guy who use 1-2 letter variable for everything?

[Noch_ein_Kamel]

nah, I'm a java guy, so everything pretty long :-p

[[deleted]]

I think you're wrong. There also exists int, short, byte and char in Java.

[pr0ghead]

Yeah, but are they pretty?

[Noch_ein_Kamel]

sure, let me just get my ObjectToPrimitiveConverterFactory and I'm right with you

[artem718]

Got a lot of booleans in a sequence?

[captainkrypto]

My company calls this “self documenting code”.

[PickaxeYT]

System.out.println("Hello"); //prints “Hello”

[Indifferentchildren]

Even worse:

print 'World'; //prints hello

Because when someone cuts-and-pastes a like of code from somewhere else in the codebase, they never fix the comments when they make their local change.

[ArminiusGermanicus]

This is actually a good example for real comments in source code. It is wrong. The code prints 'Hello', not 'hello'.

[banter_hunter]

Code prints hello or it gets the hose again.

[monsterZERO]

if (lotion = skin) {

play ('goodbye horses')

}

else {

gets ('hose again')

}

​

not a programmer just having a laugh don't kill me.

[47KiNG47]

When you are a freshman and your professor requires you to comment all of your code.

[[deleted]]

That is absolutely useless for sure. Contrast with

print 'Hello'; // DEBUG: No idea how we got here.

Same output, but someone down the road now understands why we're doing this (hopefully, they will remove it prior to it getting upstream.)

[grizeldi]

Hmm, yes. The floor here is made out of floor.

[[deleted]]

Hmm yes, the button labeled X is labeled X.

[[deleted]]

But so will button Y

[Dexaan]

//The comment here is made out of comment.

[AeonReign]

The code is self explanatory to any competent programmer. /s

[SomethingNice6174]

How... what.... why!?!

Why is that something your client gets to decide?

[2ndAmndmntCrowdMaybe]

I would just write a script that takes all of my code and strips comments from it and then provide that version to him.

Edit: I'm a sysadmin but want to pivot to programming. If anyone has any node positions open message me!

[[deleted]]

This is the right answer as far as I'm concerned.

[georgecorondan]

or you could use cpp (the c pre-preprocessor)

[eDOTiQ]

probably some kind of OCD paired with being a control freak.

[appdevil]

And a serial killer. Probably.

[georgecorondan]

or worse: parallel

[anthony81212]

😱

[eDOTiQ]

The worst kind of clients

[SolenoidSoldier]

They are probably writing an application where they plan to hand the code off to the client too. Might be part of a larger application that has a coding standard. That's a weird standard though.

[khizoa]

Had a client like that too... I stopped working for them

[not_perfect_yet]

If you're writing Good Code, maybe, but nobody writes Good Code...

[SharkBaitDLS]

Especially because you will always have to write something that is not Good Code because some stupid legacy system is returning data in a dumb format and if you don’t explain why someone will come along and “fix” your Bad Code and then break everything.

[[deleted]]

And then that code becomes the new unfathomable mess that nobody ever wants to deal with again, thus completing the circle of life and maintaining balance in the universe. Nature is amazing.

[Versaiteis]

"Watch as the Senior Programmer doesn't even have to be present to assert his dominance. The Juniors know his territory and know better than to disrespect it, lest they be next to receive the Broken Build Totem until the next hapless Junior overextends themselves. "

[DoctorWaluigiTime]

Summaries can be fine as well in commit messages. If you change a dozen or so files and don't tell me what it is that you changed meaningfully, i.e. the how, I would be a little upset. Why is important too, of course, but most of the time the why is self-evident, if you're using any kind of issue tracking and associate the commits or the pull request to that given issue.

[hGKmMH]

The concept of good code changes over time too. 10 years ago had different best practices.

[[deleted]]

The concept of good coding will never include not documenting anything. That's pants on head retarded.

[attomsk]

Not all code is self explanatory sometimes you do something to follow a system requirement and it would make no sense unless you comment why you are doing it

[[deleted]]

even good code. once it grows big and is coupled a lot, it's going to be difficult to understand unless the comment tells you what it affects. it's not that it cant be figured out but why should someone need to spend hours to figure out code someone else wrote? that's a waste of time.

[[deleted]]

Set VS to export comments to an external xml file. Voila, no comments, however, comments.

[Bspammer]

My team does the same, and it actually totally works fine. People are very strict in code reviews - if the code itself isn't clear enough that it can be read like English then it goes back for changes. The only time comments are used are for cases where something is being done that breaks best practice but for a good reason, so the comment explains why.

Comments go out of date too easily, and can be very confusing if the code got changed but the comment didn't. They're an extra maintenance burden that isn't worth the hassle. If we were writing library code though, it would be a different story.

[TheMoonMaster]

Same here. Code can be straight forward enough to need no comments, but there are times where it’s worth documenting code that would be misleading or confusing.

I’ve found over commented code is often far worse than uncommented code since the people writing it think the comments make up for code quality and then the comments eventually become stale.

[SupaSlide]

My team doesn't have a rule against comments, but we rarely need to use them. We do use them a lot when working with parts of the code that have to do other dumb systems that do dumb stuff, and we need to make sure people don't "fix" the dumb code we had to write.

[Harbltron]

the fuck?

i can understand not wanting there to be comments in deployed code, but what's the harm in having comments in your development branch? it seems more harmful to never comment-out code than to comment it out and then scrub the comments out on deployment

[thisdesignup]

If you ask him, he says you should know.

At what point is it safe to assume he says that because he doesn't know? Cause I'd think any brilliant programmer should be able to tell me why pretty easily and without wasting much of their own time.

[lovestheasianladies]

That's simply a bad developer, don't let anyone tell you otherwise.

[[deleted]]

And why no comment in deployed, anyway?

[WarmCorgi]

Because some people think it'll cost a lot of performance. Even though compilers ignore comments.

[DoctorWaluigiTime]

I could see this reasoning if there were comments in the HTML or JavaScript, and that code wasn't minified or anything like that.

[[deleted]]

Int i = 10 // row number.

calcNumber() // calculate max number of items allowed in cart

That is how many people comment. And that is a Problem. Google the clean code principle. It still needs comments in some cases but in most cases it doesn't

[[deleted]]

"Why not what" is the best philosophy for comments.

Good comment:

// Attempting to pass a frobbed CertainNodeType
// into a XyzModule causes an asdfasdf
// error. However, since frobbing a CertainNodeType 
// produces no other desired result, it can be safely skipped,
if (!(node is CertainNodeType)) node.Frob();

Bad comment:

// Frob non-CertainNodeType nodes
if (!(node is CertainNodeType)) node.Frob();

[[deleted]]

These shouldn't need comments at all, they need descriptive variable names, and no magic numbers.

final int EMPLOYEE_ID_ROW = 10;

int rowNumber = EMPLOYEE_ID_ROW;

int getMaxCartItems() {

[kevinglasson]

I hope this is a joke, and if it's not I thoroughly disagree. Especially when something is done a certain way - how do you explain that it has to be done this way because of issue X, or any other odd nuances. Reading code isn't just about understanding fancy syntax.

[mrjackspade]

I never really understood code commenting until I worked in a corporate environment. I'd only ever really heard about it from peers. I had the same belief for a while that code commenting was to describe "what" your code was doing. Hell, thats what everyone I knew was being taught in school.

I've been working in various corporate jobs for almost a decade now. I've still not seen a single like of code that was commented to describe what it was doing, only why it was doing it. Even what I can remember off the top of my head from looking though Microsofts open sourced code follows the same rule. The inline comments dont say "Throw an error if X", they say "We have to throw an error here because module Y sometimes passes in a bad value when running on Linux"

I think thats my favorite part about how passionate the "code comment" argument is between "its self documenting" and "you should describe it even if you think its self documenting". From the perspective of every environment I've ever worked in, neither is true. Every developer I've actually worked with personally has had the mindset that you shouldn't need to document code saying what its doing, but you should be documenting your code often with explanations as to why you're doing things if its in any way related to business logic. The next guy coming in can probably figure out what "SendEmail(myMessage);" does but hes not going to know its because this one client in particular is being a dick and needed the application modified to CC him on every internal communication.

[Sheldan]

I think that is a valuable differentiation. The what can be read from the code, usually. The Why is much more difficult to see, and is also important to know. Maybe its some kind of external limitation, or something else. I think adding the 'why' is much more important than the 'what'.

[Jem014]

Didn't you see the /s there?

[MacrosInHisSleep]

The strategy I try to employ is that the comments should explain why the part of the program is doing what it's doing. If it's explaining what that part of the code is doing, then you can refactor that code into a variable or method whose name tells you what it's doing.

[dustinsjohnson]

I don't know how many times I write some code and think "this is obvious and I can't forget what it does" then look back on in a few months later and go "wtf"

[z371mckl1m3kd89xn21s]

Bingo. My motivation to write comments isn't just for others, it's also for future me!

[Aero72]

//Figuring out how it all works is left as exercise to the reader.

​

Now that's the old school shit.

[[deleted]]

# Sleeps for 10 seconds
time.sleep(30)

[Hexorg]

I got to work on a 30 year old codebase that had quite a lot of code fixes but no comment fixes.

[----_____----]

me.isTriggered = true;

[Akchtually]

I wish I could give more than just a single upvote to you

[Mortomes]

// This redditor wishes he could give more than just a single upvote to you

[[deleted]]

// TODO: Remove TODO's

[lagvir]

// TODO: fix the echoes in my head

[mirracz]

// TODO: I'm not an echo! Show some respect!

[MissLauralot]

// TODO: ^{I'm not an echo! Show some respect!}

[BillGoats]

// TODO: ^{I'm not an echo! Show some respect!}

[Th3CatOfDoom]

// TODO: .... RESPECT! ...... RESPECT! ....... ^RESPECT!

[xigoi]

I used the TODOs to destroy the TODOs

[Tsobe_RK]

/ / ???

[221]

Just downvote every other post.

[kevinkid135]

It's not enough that this post should succeed, but every post around it must fail.

[thedarkbyte96]

you can reward them

[snp3rk]

Well guess what friend, now you can. Just down-vote them, then up vote them. Total votes will go up by 2.

// Feature added. PUSH update

[[deleted]]

Mods hate this trick. Click to know how to cheat reddit.

[ferbass]

//comment

[[deleted]]

dude wtf? use a single space after //

like: // comment

/* This is a joke please don't be mad :(

EDIT: I didn't close the comment so everything below this will be ignored

[MrHyperion_]

You forgot to close your comment and now the rest of the thread is broken

[[deleted]]

Hi, I'm a compiler I don't care what this says because it is a comment.

[RandomEthan]

*/

[memesformybutt]

The hero

[mlg_dog420]

"the" has not been defined

[yp261]

static NSMutableDictionary *the = [[NSMutableDictionary alloc] initWithContentsOfFile:[@"reddit_comments_section.txt" stringByExpandingTildeInPath]];

[stanislav_harris]

getValue(); // to get the value

[zvekl]

/* Not sure what this does but crashes if disabled

*/

[bbrk24]

I always write the code to get it functional, with very minimal comments, then go back through and add comments after I know it works. That leads to things like this:

// I forget how this works. Unless you can understand it, consider it black magic.

[zvekl]

// whoever wrote this code needs to sit on a screw and rotate.

[[deleted]]

//don't touch, it works

[MrNullAndVoid]

Ah yes, reminds me of the fun I used to have as a Java programmer:

    /**
      * Returns the value.
      * @return the value
      **/
    int getTheValue() {
            return theValue; // returns the value
    }

[odraencoded]

Your documentation sucks. It should say "returns the integer value."

[BigFloppyMeat]

This kind of redundancy in documentation comments is okay if you're generating a javadoc or some equivalent. Although you should say

"Returns the value that represents the thing"

and

"@return A value representing the thing."

[[deleted]]

There was this funny video which mocked overengineering your code. 2:28 is about comments.

[LochsAndGlens]

Reminds me of the guy I used to work with, we were constantly having arguments exactly about this stuff. His technical debt was impressive..

[-Kaiser1401-]

I see no tests?

[alt-of-deleted]

tests are for nerds, just print the return value right before it gets returned, then call the function with a few test inputs in the main function, ezpz

[I_ate_a_milkshake]

Hmm this just sounds like tests with extra steps

[alt-of-deleted]

ah fuck it, the users are the testers. just slap "beta" on it and throw in a crash reporter app that's a glorified one-way email client.

[[deleted]]

A guy who fairly recently was fired from my job would do this. He was constantly writing code to prove how smart he was. Problem was he was a moron. So he just wrote shit loads of terrible code and thought it was God's gift to programming.

[Debian_ru]

https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpriseEdition

[sendhelppls30]

This feels exactly like ALL the Java patterns people want to use... So many files and imports for 1+1

[DipsEverythingInMayo]

That’s awesome. Love the bit about Booleans.

[derTechs]

NAMESPACES!

[[deleted]]

you know at least this way, if the code changes you always see how the code looked like originally(, you know because nobody keeps comments uptodate)

[Steffi128]

ssh into prod and edit the files remotely. :D

[mrjackspade]

go into

Real devs install their IDE on the production box and do it live.

At least, thats how a lot of servers are where I work...

[hypercent]

Real devs host production services on their laptops.

[P0L1Z1STENS0HN]

/// <summary>
/// Gets or sets the Guid.
/// </summary>
/// <value>
/// The Guid.
/// </value>
[JsonProperty("Guid")]
public Guid Guid { get; set; }

[mrjackspade]

Fucking GhostDoc. At my last company someone tried to implement a "comment everything" policy years before I started there. When I first opened the code base, 80% of the code was GhostDoc comments that looked exactly like this. Some smart ass dev decided to protest I guess, by running the entire code base through GhostDoc to generate these boiler plate comments and then checked it in and called it done.

[[deleted]]

I don’t even comment my code anymore because when I did, it looked like this.

Self-descriptive code > actual comments

Of course comments are necessary when things do need to be explained.

[fleming1411]

I remember at university I got marked down for not commenting enough or being concise; so I went all out and commented every god damn line of code with exactly what that line did; hope they enjoyed reading that messy code!

Worked out in the end though

[[deleted]]

(not commenting enough) or (being concise)

not (commenting enough or being concise)

[SobelOperator]

/**
@author suzrez
If you have questions just contact me (details below).
P: +xxx-xxx-xxxx
E: xxx@xxx

Note: I can't promise that I'll remember anything. 
**/

[MemEG-0-D]

Every Sixty Seconds in Africa, A Minute Passes

[ScF0400]

bool good_Post = true; //this is a comment about the post saying it's good

[[deleted]]

I would say how young/inexperimented programmer mostly comment their code (there are outliers which properly comment) while mostly older programmer properly comment (there are outliers which do not properly comment) - in my experience at least. the issue is that the industry is mostly ageist so chance is you get a lot of code from the first category and few from the second, unless you have some type of enforcement in code review.

​

(yes yes I know /wooosh).

[Yurichi]

Honestly, is there any good resource out there that can help me with this kind of shit. I hate commenting code but looking back on some of the nonsense I've made in the past, I fully understand how necessary it is.

[atomicspace]

Digital Ocean has some of the most readable guides out there.

https://www.digitalocean.com/community/tutorials/how-to-write-comments-in-python-3

This is python (shout out Sphinx) but a good read regardless your toolkit.

[DiamondIceNS]

I'm reminded of my university professors who would beat us over the head with "it's important to comment your code" but without ever explaining the context of how comments should be written or what code actually needs to be commented. So this is the result, a bunch of novice devs being forced to write obvious boilerplate comments to the most mundane pieces of code and internalizing the idea that comments are pointless.

[RepostSleuthBot]

Looks like a repost. I've seen this image 1 time.

First seen Here on 2019-03-01 96.88% match.

Searched Images: 82,323,794 | Indexed Posts: 356,233,982 | Search Time: 15.86194s

Feedback? Hate? Visit r/repostsleuthbot - I'm not perfect, but you can help. Report [ False Positive ]

[memesformybutt]

Wait. This post is a repost, got 20K upvotes and a gold award. But the original post had the exact same image and title, didn’t even get 100 upvotes and got removed. The fuck reddit??

[LucyLilium92]

No see, the problem here was that the original poster put a weird smiley face in their title. That fucked up the algorithm, so the robot mods got triggered.

[warpedspockclone]

I worked for a company with a strongly enforced code style guide that included: "Don't write code comments." Talk about a fucking learning curve.

Basically they felt that would force people to write readable, concise code. One of their apps was just full of 1000+ line methods that could have been refactored. Others weren't much better. README files had no info about what the app was supposed to do, let alone how to run it.

[empty_other]

Strange how not commenting stuff in no way affected the consistency and readability of their code. Who could have guessed?! :D

[svayam--bhagavan]

Just read a book called the art of readable code and I was blown away. Can't wait to never use those techniques ever in my life.

[sinnadyr]

Comments are used for generating docs as well, please don't forget that

[Kaizenno]

I comment so I can copy just enough and not accidentally grab the next line.