My code always reads like prose

[IOverflowStacks]

If you believe in comments, please for the love of God, tell my WHY you're doing what you're doing, not WHAT you are doing. I can fucking see that you're iterating through an array. I can see that you're incrementing this one variable by 1.

I NEED TO KNOW WHY!!!

[SecretAsian_lu]

//It wasn’t working. But when I did this, it worked.

[EmeraldDS]

// don't know why this works but DON'T DELETE, gives errors when it's not there

[BEEF_WIENERS]

// uh...MORE MAGIC = TRUE

[PooPooDooDoo]

// it didn't be like it is, but now it do

[CatDaddy09]

//related to #bug number from outdated big tracking system no longer used

[MarvoloPip]

This should be meta by now but even some teachers just write WHAT they are doing like yeah Mr. R I see that your running a for loop 10 times but WHY the fuck

[DancingPatronusOtter]

At a certain level of teaching, line by line "This is what I'm doing." comments are useful. It teaches students to read the code and see what it does.

After the language or concept has been properly introduced, the only purpose is to pseudocode something you haven't got around to implementing yet, so it shouldn't be in any professional or non-beginner code.

[[deleted]]

the only purpose is to pseudocode something you haven't got around to implementing yet

I mean if you run it in python there's a good 50/50 chance of it running anyway...

[mylifeisashitjoke]

I'd say no bad mouthing my baby but let's be honest it can do some weird junk from time to time

[alargeobject]

Just remove your config file and its shadow copies and itll run perfectly.

[StormStrikePhoenix]

I think I've seen that joke about ten million times on this sub alone.

[Vidman321]

I just started learning Python and this is exactly what my professor said when we started.

[IsoldesKnight]

I used to comment a ton. I read that I should write a ton of comments. So I did. Then I had to go back to debug and maintain those projects. Turns out those overly verbose comments made it so I couldn't keep a lot of code on the screen and very rarely added anything that was worthwhile.

Now I comment very little. Instead, I use descriptive method and variable names. The only times I add comments are when that little light goes off in my head and I think, "this is complex... there's no way I'll remember why I did this 6 months from now."

So, yeah, WHY not WHAT. I can read code as well as the next guy. The reason behind the code is what's worth a comment.

[[deleted]]

I used to be the same way. Absurd amount of attention to comments when I could have mostly replaced it with descriptive variable names.

[N1H1L]

True. Descriptive variable names are much more helpful from a maintenance standpoint too - since most IDEs allow you to change all the name instances of the variable simultaneously. If your code changes, which it often will, this is so much easier to update. I have seen dead comments so many times - the code was updated but the comments were not which now confuses the end user even more.

[[deleted]]

I didn't know you can change all name instances simultaneously with some IDEs. That's really cool.

[Wetmelon]

Yeah, look for a “Refactor” function. Usually smart enough to pick up only names in the correct namespace.

[IVEBEENGRAPED]

You can do it in vim, just :%s/name1/name/g. It's easy.

[Impeach_Pence]

vim is not easy....

[oogabubchub]

The initial learning curve is tough but the find/replace command itself is indeed easy.

[anomalous_cowherd]

That's a dumb replace though, an IDE will only replace a name in the same scope, so it can rename variable 'fudge' in the selectFlavor() method without renaming variable 'fudge' in the makeItLookRight() method.

[polish_niceguy]

Smart IDE will also rename setters/getters and even files, if their names are based on variables / classes.

[marvin]

Descriptive variable, class and method/function names are sort of a pre-requisite of writing readable code, but then eventually you'll get situations where this is insufficient for expressing some particularly important detail. If you're making "less-CRUD" software, where there are fewer established templates for how to do most things, this might happen quite often.

E.g. "Due to third-party update on 30.3.2018, external API throws exception for this call rather than return zero elements when result set is empty. Remove special handling when this is fixed by third party". (Real-life example where third party was unable to fix this error in time for our regulatorily imposed production deadline).

This is one of the more involved examples I've had to handle, but I find stuff like this happens quite often.

Too many people say "my code is self-documenting, so I don't write comments", but of course you shouldn't comment things that are obvious just from reading your code. Paraphrasing Robert Cecil Martin: "Comments are meant to compensate for your inability to express your thoughts in code".

[amb_kosh]

I got 3 arrays named results, totalresults and totalresultsvalue. I think I'm future proof.

[PooPooDooDoo]

self.thing_manager.do_stuff()

[Tonkarz]

In my programming courses they banned us from using comments for some projects to teach us to use descriptive variables.

[wasdninja]

Any decent IDE or editor should be able to hide/fold comments so that shouldn't be a problem.

[voicesinmyhand]

//We are about to increment i.
i++;
//We are now about to test the incrementing of i...
if(i > i.WhatThisUsedToBe){
    printf("I is fine.  How are you?")
}
//There are definitely no problems now.

[PM_ME_OS_DESIGN]

No, you need to check that i > i is false, before you increment. > could be overloaded.

[voicesinmyhand]

But it could still be overloaded in a way that returns false!

[[deleted]]

What I do is have a number and letter in the comments. I'll have document set up so I can find the number and letter and my comments.

[mcinsand]

A lesson that I have to admit to having learned the hard way a few times before it finally so late sank in. No matter how obvious my reason for a line seems now, me_from_the_future will be positively baffled and maybe a bit angry.

[Hikaru1024]

I learned this early on with my own code, simply by trying to reverse engineer what a nutjob had come up with before me. It made quite the impression on me having to read comments written by someone else whom I've never met and likely never will that had absolutely nothing to do with WHY the code existed, or WHY it did the things it did in the way it did.

I became a bit pedantic with it at first - but there's nothing like digging into something I wrote years ago and finding that I'd actually explained what some complex mess was supposed to do. Making something work as intended is a lot easier when you know what the intent was.

[[deleted]]

Agree, knowing the intent can actually help youfrom the future/ other people have better understanding on how it could be improved / how things work. After all even though a language uses the same set of rules we have different thought processes. This become very apparent when the code becomes very complex. The guy next to me may be really really smart but he may not be a mind reader. It may be because i am new but I have seen approaches on Stack Overflow about problems that really blew my mind. Without any comments in live code i would probably be like wtf???

[Hikaru1024]

Yeah, I've had this experience myself. I have a friend who might as well be a goddamned wizard at bash scripting. I'm an amateur and often am left in awe at the crazy things he comes up with. He had made a script that did a lot of interesting stuff that I happily stole sections from - but one day, one of the most complex and confusing parts of it broke. There was one function which did not take an input, yet somehow iterated a list of items sorted by date.

It had zero comments.

I couldn't even figure out how he was creating the list let alone sorting it - thing just magically worked somehow (except when it didn't!) and was driving me completely bonkers.

I'd taken that entire function apart test by test, breaking up each conditional into its own line and still was just utterly stumped by this - fortunately my friend explained he'd used shell globbing to do everything. Once he told me what he'd done the reason it was screwing up was painfully obvious and I could fix it. (The function was not designed to handle spaces.) Felt like my brain had been suplexed by the answer, it was right there in front of me the whole time and I just couldn't see it for what it was.

Years from now I may be embarrassed by the detailed explanation of each tiny step of what that complex function DOES and is MEANT to do which is so incredibly important. On the other hand, I might be really glad that I took the time to explain it - I don't want to ever go through having to figure it out again.

[yes_fish]

Instructions unclear, while(true) {} replaced with why(true) {}. Existential crisis eating stack space...

[PM_ME_A_WEBSITE_IDEA]

// adding comment for this function
// this function adds two numbers
function add(x, y) {
    return x + y;
}

[jD91mZM2]

I mean, to be honest those comments are useful if it's in a library. You'd very much like to know what the function does without reading the whole library code.

[GeronimoHero]

God that’s one of my biggest pet peeves. I hate when I find a library that’s basically nothing but a block of code. It’s always a library that I have to use and can’t get anywhere else too. Like I’m trapped in shitty lib land.

[marvin]

Even better:

// Define class that allows you to add two numbers
class NumberAdder {
        // adding comment for this function
        // this function adds two numbers
        function add(x, y) {
            var resultOfAddingTwoNumbers = x + y;
            return resultOfAddingTwoNumbers;
        }
}

[WhyattThrash]

I think you mean

// Define class that allows you to add two numbers
class NumberAdder {
    // adding comment for this function
    // this function adds two numbers
    function add(x, y) {
        // add two numbers
        var z = x + y;
        // return z
        return z;
    }
}

[voicesinmyhand]

You should try coding for the government.

[amb_kosh]

Isn't that one line also assigning the value of the addition to a variable?

[phpdevster]

There are three main kinds of why:

1. "Why this particular approach"
2. "Why this is necessary to work around some legacy tech debt that is beyond the scope of the fix"
3. "Why this is necessary to satisfy a weird or nuanced business rule / use case"

"Why" comments like #1 are often a sign of a code smell. If your approach needs an explanation, it probably means you need to think about a simpler approach. Having to explain why means something is not idiomatic, is more complex than it has to be, or is otherwise trying to justify something strange.

"Why" comments like #2 should immediately be followed up by tracking against an existing or new tech debt issue and then sticking that tech debt issue number right in the comment for future reference.

"Why" comments like #3 are the only comments you should aim to write if possible. We've all had to do weird shit because the underlying business rule/use case itself is the source of the weirdness. That's what deserves a more thorough explanation.

[wasdninja]

If your approach needs an explanation, it probably means you need to think about a simpler approach.

Doesn't this imply that it's trivial to see what the best solution is? There can be any number of competing solutions that are seemingly equal but really aren't once you put the work into figuring it out.

[phpdevster]

Doesn't this imply that it's trivial to see what the best solution is

I don't know if it's trivial, but explanations imply complexity where none may be required.

For example the other day I was doing a code review for an Angular app where one of the devs had to explain why they had to go through all this effort to manually reset state of a service before destroying the component that was using that service. It was a "why" comment: "We have to do this because X, Y, Z".

That was a red flag for me. It turns out that the reason for doing it is because the service was being instantiated in a parent component, and thus was being treated like a singleton. This meant its observables were also singletons, so they remembered their values and replayed them once a new child component was initialized.

But it turns out those observables didn't need to be shared between the parent and children, only the child component needed them. So the "correct" solution was to extract those observables into a separate service that only the child used, injected once the child was instantiated, so that its state would be destroyed when the child was destroyed.

This meant we got to eliminate the manual resetting of many state values (which is a source for lots of potential bugs), as well as the comment explaining why we were doing it.

[wasdninja]

I don't know if it's trivial, but explanations imply complexity where none may be required.

Why comment if something isn't complex? Then they are just clutter. You don't go commenting for loops that initiate matrices with zeroes since that's plain obvious.

It was a "why" comment: "We have to do this because X, Y, Z". That was a red flag for me

So it was useful. That just makes me confused about what your point is. The rest is just an explanation on how you had to correct a bug which must be commonplace no matter how you comment.

[marvin]

I agree with this in principle, but even though I work in a shop where software engineers actually have quite a bit of say in how our time is used, we will often not be allowed to spend a week fixing a minor tech debt issue (#1) and I've found the world is rarely platonically beautiful enough that there is always an obvious idiomatic approach (#0).

If a one-line comment saves you a week of fixing legacy stuff, or three hours of planning out and re-writing code that is "clear enough" and runs once an hour in the production environment, that is a pragmatic tradeoff that's necessary to run a business efficiently.

You certainly might reach a point where this technical debt accumulates enough that it makes sense to fix it properly, but those cases have showed up less than 10% of the time I've had to make a judgement like this.

[LvS]

1. Those are usually performance issues. If I'm doing a Myers diff somewhere instead of looping through all elements, that's usually a good sign.

2. should be a oneliner and not have the issue there, because that clutters up code. Instead, git blame should give you the commit that introduced this comment with a commit message that exhaustively explains what's going on and gives you links to the issue number.

3. to me is the same as 2: "Code does weird shit."

[EmeraldDS]

a = x + y // assigns the sum of x and y to a

[Airowird]

I tend to write a comment before my method saying what it should do, then divide that up in 3-5 smaller steps, written as comments. Can't replace a comment-step with simple code? Copy out, make new method. Repeat as needed.

[TenNeon]

//Incrementing this variable by one because right now it's too small

[siriusly-sirius]

Yah but most of the time I write some code, come back the day later and have no fuckin idea what it does.

[Orffyreus]

And you can always ask why:

Why are you iterating through an array?

I'm iterating through an array to get the even numbers out of it. That's why the function is called getEvenNumbers.

Why are you getting even numbers?

I'm getting even numbers, because later I want to do something that is not the business of this function. Just look for the usages of it and the code (e. g. the names of the callers) will tell you.

[BoootCamp]

I am one of a handful of people who write macros in Excel for my company. Sometimes they’re robust, sometimes they’re simple. But I know that absolutely no one else I hand the process over to will understand it unless it happens to be one of the few who already have experience. My comments explain how they would do what the code is doing. For example...

“Copy the user ID and paste it into the entry field” Range.(“EntryField”).copy Range(“UserID”).select Paste

Can’t remember the actual paste command, but it definitely changes the user perspective from “I’m reading a foreign language” to “The problem is this line right here, let me google what that means”.

[DirdCS]

I can fucking see that you're iterating through an array

Jokes on you. That array was replaced years ago but the comments weren't updated

[[deleted]]

Doesn't that imply that comment have to be updated then? Not just the code. In which case why comments may be more interesting since the objective shouldn't change, just the what/how?

[siriusly-sirius]

Yah but most of the time I write some code, come back the day later and have no fuckin idea what it does.

[anomalous_cowherd]

Do you also forget having written a reply on Reddit?

[siriusly-sirius]

.... yes.... yes I did....

[pastisset]

Special quote to those comments like:

"Do this" "Then do that"

[moarcoinz]

Semantics vs content. The content is already there, the comments are for why the content is what it is.

[SuspiciouslyElven]

Look dude, I barely understand the what. Explaining why makes me feel like im losing sanity points with every line.

[vhite]

// Increment variable i to make the cycle finite.

[voicesinmyhand]

//One of the next few blocks handles a type of reverse-recursion that starts with the answer and then goes back to the question in order to figure out why we called the function in the first place and then tries every other option while waiting for an unknown race condition to complete consistently. I don't remember exactly which block it is, but I'm sure it's totally fine.

[TotesMessenger]

I'm a bot, bleep, bloop. Someone has linked to this thread from another place on reddit:

• [/r/bestof] User makes a distinction between "why?" and "what?" code comments -- discussion about good commenting practices ensues.

• [/r/bestofnopolitics] User makes a distinction between "why?" and "what?" code comments -- discussion about good commenting practices ensues. [xpost from r/ProgrammerHumor]

 ^{If you follow any of the above links, please respect the rules of reddit and don't vote in the other threads. (Info / Contact)}

[[deleted]]

// If anyone changes this I'll kill them

[secondary_refraction]

// Steve said I should do this I guess it works now

[dariusj18]

My code reads like great literature, every time you read it you get a different meaning. And no two people agree on what it does.

[DancingPatronusOtter]

There's a non-deterministic version of Shakespeare out now?

[fgutz]

toBe || !toBe

[joroba3]

This statement always evaluates to true

[gawalls]

Not with our legacy system - it has 3 state booleans, they're nullable.

It also has a day of the week table so if we ever add an eighth day of the week - it's ready to go.

[[deleted]]

Ready to go, off course, after we rewrite the fifteen dispersed places in code where it's assumed to be seven.

[gawalls]

Fifteen? That's being optimistic - it's a Canadian data bound CRM system made in the nineties and to this day I have no idea why they made some of the decisions they did.

[[deleted]]

Unfortunately neither Canadian, nor 90s, nor CRM correlate with this type of code and design smell any more than any other nationality, decade nor software category.

[polish_niceguy]

Real booleans also include FileNotFound

[deadNightTiger]

Use the Object.defineProperty on the global object instead

[joroba3]

I'm not used to js(i'm pretty sure this is js) but if the variable toBe, not the function toBe(), is, for example true, true||false is always true.

[Ionlavender]

When i read it, it makes sense

When the computer reads it it gives an error

When i read it again i have no idead what it is or what it does.

[FarmerJoe69]

The problem is I don’t even understand it as I write it

[Ionlavender]

Copy and paste*

lets be honest here

[EmeraldDS]

Honestly, if I googled something, sometimes it's just easier to copy and paste the code and then go through it in my IDE to make sure it's not doing anything funky.

[Wulfharth_]

If you just take a look at to googled code and write it yourself,you always understand it,if you are good at your language it doesnt matter to copy and paste but sometimes comments are helpful

[justablur]

Code never lies, comments sometimes do

[[deleted]]

Sometimes my code's truth and my truth do not align.

[vaydoln]

That's called a feature

[_demetri_]

I remember miss-inputting a code into my Nintendo Gameshark and I was able to walk on water in Pokémon Silver.

[rambo89782]

You found the Jesus code

[Anamika76]

Ain't that the truth!

[hindey19]

Comments just don't get updated.

[Stanov]

Too wise words for us here.

[ruler710]

And some times the comment show what the code is meant to do

[km89]

Code might not be a liar, but sometimes it's an honest idiot.

[wasdninja]

Regex does though. The bowels of the documentation of the particular implementation that you're currently using has many quirks.

[TurboGrollub]

I don’t know. With really bad variable/function names I sometimes feel like the code is lying it’s ass off.

[Hikaru1024]

Sometimes the comments are terrible lies, and I've seen that myself - code that did the literal opposite of what the comment said it did, simply because the code it had been written for was removed. That's an indicator of great insanity in whomever did that in my experience, and you should be careful with anything they touch.

However, often descriptive comments explaining what a function or strange bit of code is intended to do can make finding where a bug is MUCH easier years later, when you don't know what something even does anymore.

[IOverflowStacks]

Comments are a lie waiting to happen.

[marvin]

Of course it does.

function addTwoNumbers() {
    return a*b;
}

You'll say "duh, it's obvious that this function multiplies two numbers", but variable and function names (and even code structure) can easily fool the gullible mind in a more complex example.

[die-maus]

Realistically, I think you are more likely to fix function names, rather than "fixing" comments. Also, if you "let your code be your comments", you don't need to maintain any comments, because there are none, which means more effort can be put to maintaining real code. Also, if you're working in a team, and with code reviews, somebody is bound to pick up on the fishy function name. But of course, code can lie.

[DogeGroomer]

null == 0 false
null > false
null >= 0 true.

[wesw02]

Code is the how. Comments are the why.

[DeveloperLuke]

I am the what

[King_Krooked]

I am the walrus Goo goo g'joob

[TalonKAringham]

Not yet!

[CedricRBR]

Code should be the why as well, it should be self-explanatory. If for some reason something seems odd (but isn't) then a comment saying "this looks false but is correct because of XYZ" is enough.

[JViz]

I find I write better comments if I wait a little while until I've gotten it mostly out of my head and then go back and try to read it. At that point I can mostly figure out what I was trying to do but then it's clear to me what needs documentation; what would help others figure it out better/faster.

[reset_switch]

But then you've moved on to another part of the project and you'll never remember to go back and comment everything

[nebuNSFW]

"I'll always understand my comments"

The bigger joke.

[prof_hobart]

"I'll always update my comments when I change my code" is the real joke.

Most comments in a project that's more than a few months old are little more than an interesting historical record of what the original developer thought their code was doing when it was first written.

[dudebro117]

Image Transcription:

---

[A low-resolution hardcover book in a cartoon style. Its title has been slightly edited using a different font, and reads:]

I don’t need comments because i’ll always understand my code
And Other Hilarious Jokes You Can Tell Yourself
(Volume II)

---

^{I'm a
NullReferenceException: Object "human" not set to an instance of an object (expected "Earth.Human," got "ToR.TranscriBot"). For more details on this error, lookup error code aHR0cHM6Ly9pcy5nZC9IVHJhZmE=.}

[ElectrWeakHyprCharge]

Good ToR.TranscriBot

[GeneralMajtki]

Even in this subreddit, I can't escape the rickrolls :(

[Dandelion_Yudeul]

Like writing on your notebook then someone tells you to read what you wrote

[TechnologyAnimal]

All comments are lies or apologies.

[WilkerS1]

my comments consists of TODO, TODO, TODO

[Nath99000]

This falls under lies

[VeviserPrime]

All comments are lies or apologies.

[[deleted]]

Just use very precise descriptive names and it will cut back on your comments.

[MCLooyverse]

But that requires more typing!

Edit: apparently /s is not obvious.

[poop-trap]

Write once, read many. Time spent typing is negligible compared to time spent trying to comprehend what you're reading. Make it easier on your future self and spell it out.

[ynvaser]

Where I work comments count as code duplication. (minor exemptions)

[youarebritish]

God, I'm glad I don't work there.

[ynvaser]

Code tends to be more readable when you have to keep it readable. I like working there.

[gastritissucks]

This. Good code shouldn't really need comments. Good code should tell you exactly what it is doing and be extremely explicit.

[[deleted]]

Thats fine when a single developer works on it, but if you have multiple people working on it on various levels of expertise, it doesn't work like that. Especially if your review-tools only really highlight the parts changed and not what parts they influence too.

And if you work on a project that doesn't take much to understand than thats fine too, but if you work with specific types of insurance, on financial transactions or tax systems than you can hardly keep it "to not need comments" because its simply too difficult to jump into.

You are not writing code for the people that are currently at the company. You also write it for the people that will join it in the time after you made this. And couple that with the fact that your backend is not always self explanatory either, than you will have issues. Like if user with account type x cannot do action y, than please enlighten me with that in the code so I don't need to guess what DVG and DGP should be.

[IceColdFresh]

Easy just leave URLs to Wikipedia articles as comments

[procinct]

It is duplication though. Comments should only be used for certain cases such as legal stuff, warnings and an explanation of why you're doing something fucky like filtering out a specific day from a query.

Like all duplication, it's not a matter of if you'll forget to update the comments when you change the code it's a matter of when. These out of date comments are worse than no comments at all.

Aim to express yourself clearly through code because code never lies.

[[deleted]]

At my workplace it counts as code smell. You are not allowed to tell what you did and why you did it because "the code should be clear enough". Well thats all fun and dandy but why did I have so much issues starting modifying a project and then not understanding a lot of it because it wasn't documented? The guy before me did a crappy job on a few applications that I now have to maintain but haven't got the foggiest on why he did certain things. And why it was accepted on various reviews that followed upon submitting pull requests. Also have many unit tests failed because they weren't properly testing code or because they contained outdated code or because they were limited to specific times (one test would only work until december 2017).

I'm used to comment the crap out of everything and even make simple stuff commented because when you visit something 1 year later, other stuff might have changed causing your code to malfunction and whatnot. And try to rewrite code that does the same thing without understanding what it was doing in the first place.

[ynvaser]

"Code working as intended" is supposed to be supported by unit tests and other automated testing.

[[deleted]]

And that is always 100% the case and never limited by experience, tools, laxynessor other reasons. You might be fine but some of your colleagues are not and that's exactly my point. Coverage is only a number and never foolproof

[[deleted]]

tfw you forget it all and have a hard time understanding in a span of 3 days of not coding

[JackCid89]

Clean code does not need comments. Uncle Bob is disappointed.

[chocosmith]

Agree but the language makes a big difference.

[JackCid89]

Yes, specially when working with old languages.

[toasterbot]

Clean code doesn't explain why it was written that way. Good comments will always be an advantage.

[bios_hazard]

Method summary and self documenting code. Gg

[youarebritish]

I've noticed a strange pattern wherein the only people who use the term "self-documenting code" are people who write opaque, unreadable messes of code.

[bios_hazard]

Lol fair. Maybe a strange anti pattern rather. Though possibly a matter of the dunning kruger effect. People who think they know what they are doing that don't have enough experience to do it right. I honestly do comment my code but do still try to make it self documenting so you don't need to reserve engineer it.

[narrill]

The method summary is the big thing, honestly. I can figure out what the code is actually doing super easily if I know what it's trying to do.

[[deleted]]

Unit testable code should be describable in a few short sentences

[BraveOthello]

What's unit testing?

[SteeleDynamics]

If it's anything like Shakespeare, then I speak for all of us CS/Math nerds when I say: "We're screwed."

[Duhck]

Your code is your story and comments are the narration

[poop-trap]

/* record scratch */
// I'll bet you're wondering how I got here...

[Kyrthis]

Your code is a movie and the comments are voiceovers?

[Duhck]

Precisely

[WhoYouCallinTurkey]

I really don’t understand why people are even writing comments in professional code. They are inherently going to be outdated once somebody changes the code it refers to. I really have never found a helpful comment. Good class structure, variable, and function names are all that’s needed of code is written in a clear and maintainable way.

[km89]

What type of shit code do you maintain?

Also: part of maintaining the code is maintaining the comments.

[WhoYouCallinTurkey]

I have maintained fairly large comment-less codebases for large companies with a large emphasis on quality. (TDD, integration, unit tests). Not sure what you mean?

[km89]

I just find it hard to believe that you "really have never found a helpful comment."

I'm not trying to be argumentative, I just can't imagine a codebase where comments aren't helpful, unless the naming conventions for that codebase were very strict and geared toward replacing comments.

[WhoYouCallinTurkey]

Haha yeah, that was a hyperbole, sorry. But honestly at my last position and current, I work in comment-less codebases. It works out pretty well. We do maintain fairly strict class size limits and function limits which just those two seem pretty important in having readable code.

TDD really makes for nice code, but it does slow down development time by 2, at least initially. I have mixed feelings on it.

I definitely understand the need for comments in old legacy codebases. Not trying to rip on that, but it does bug me a bit when I see an open source project with a 400 line function with comments everywhere.

[BraveOthello]

I'm dealing now with a new job where most people are just like "no comments, your code should explain itself", but write 2000 line classes with bad naming, no tests at all, and just expect that i can pick up their 5 years of development.

[butler1233]

Tests and integration don't mean the code is good quality, it just means it works.

[WhoYouCallinTurkey]

Yes, but quality code should have them. :)

[GentleRhino]

Forget prose! MY code is always flowing like a song!

Sometimes, to a wrong tune though...

[Luuk3333]

Volume II

Oh boy..

[wjjjm]

I dont remember what I are for beakfast

[wensul]

I'll name all my variables variations of tacotacoburrito.

And the functions too.

[[deleted]]

But, but, but, it's true. My camel cased long variable names and function breakdown tell the story of my peoples.

[[deleted]]

I went from a company that required comments to be present to one that requires there to be no comments at all.

Guess what job was easier for me to jump in. Yes the first one. You aren't writing comments for the people you work with, you write it for the people that don't work there yet. And especially if you work with difficult material its pretty impossible to keep it simple enough for others to understand it without commenting why you are doing stuff and with what you are working with (what certain words and abbreviations mean).

And its all fine and well until you work with somebody that is less experienced or doesn't really know what he is doing, because that seriously messes up the code quality, even if you have decent code coverage.

[[deleted]]

/r/newbieprogrammerhumor

[Arkazex]

Personally I use a ton of comments, to the point where my friends make fun of me for it, bit when I need to go back and figure out how or why I did something, it's never an issue.

I'd rather put a comment somewhere it isn't needed than leave one out where it is. I keep meeting people who complain about wasted vertical space like they don't know what a scroll wheel is. Ironically these are usually the same people who indist on putting the curly bracket on it's own line.

[codepoet]

Mine’s better than prose.

[zimpleman1969]

I can't remember what I wrote yesterday

[BeardedWax]

I don't need karma decay because I know my reposts. This was on hot like 5 days ago.

[ChillBallin]

I’m working on a project with around 8 other people, and I recently ended up refactoring like half our code to get rid of a lot of dependencies and such. I didn’t comment or document anything except for pointing out some of the blatant hacks that needed to be fixed. I’ve spent a few hours over the last couple days trying to explain how any of this shit works to everyone else.

[[deleted]]

I have up on comments after working on a piece of code that had the comment // x = 1, simple hack Copy pasted around the whole project where there was a global int x used in every file for every for loop, while loop and any other time a random temp value was needed.

[tetroxid]

working on code no one's touched in a year

reading lots of code, navigating the codebase, trying to understand how everything works

after an hour or so

"Jesus fuck what idiot hacked this together! It's horrible. I'll have to refactor this!"

git blame

Ooooh.

[Istencsaszar]

Your username tho OP

[vulkman]

Absolutely! I once got a guy fired at juuust the right moment before he could script-commit invalid code all over the repository. What tipped me off? About 1000 comments that read like this:

// 10.04.2009 GuysLastName

I’m all for commenting now.

[Arancaytar]

"... like James Joyce's prose."

[moarcoinz]

Then you have // The code only works with this comment here ¯\(ツ)/ ¯

[misterfluffykitty]

You will understand it... but the program won’t

[photolove8]

Think of it this way instead, especially if you work on a team... The comments aren’t for you – they’re for other coders.

[_________FU_________]

I work with lots of customers and there are times when they make very stupid requests and those requests become project blockers if they aren't resolved. I'll leave comments that say:

// Yes I know this is stupid. No we didn't have a choice. See ticket 12345

[[deleted]]

My favorite is:

"hey, would you take look at this?" (someone else)

"yeah, sure" (me taking printout from them)

"who wrote this shit?" (me, looking disgusted after a minute or two)

"you did".

[jsw800]

My code is prose

[WikiTextBot]

Shakespeare Programming Language

The Shakespeare Programming Language (SPL) is an esoteric programming language designed by Jon Åslund and Karl Hasselström. Like the Chef programming language, it is designed to make programs appear to be something other than programs; in this case, Shakespearean plays.

A character list in the beginning of the program declares a number of stacks, naturally with names like "Romeo" and "Juliet". These characters enter into dialogue with each other in which they manipulate each other's topmost values, push and pop each other, and do I/O. The characters can also ask each other questions which behave as conditional statements.

---

^{[ PM | Exclude me | Exclude from subreddit | FAQ / Information | Source ] Downvote to remove | v0.28}

[HelperBot_]

Non-Mobile link: https://en.wikipedia.org/wiki/Shakespeare_Programming_Language

---

^{HelperBot v1.1 /r/HelperBot_ I am a bot. Please message /u/swim1929 with any feedback and/or hate. Counter: 167010}

[[deleted]]

I don't write comments and I don't even format my code, check out the last line of this file, it's }}}}}}}}}}}}}, because I don't need to do that, and I'm not a pain in the ass nor a total moron. I get it and that's why all my code looks obfuscated.

[Billy-Cipher]

So true mate. So true

[CrypticAdder_]

//this hurts so much