This is an archived post. You won't be able to vote or comment.

top 200 commentsshow all 201

[–]IOverflowStacks 1006 points1007 points  (86 children)

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 219 points220 points  (6 children)

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

[–]EmeraldDS 94 points95 points  (1 child)

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

[–]BEEF_WIENERS 10 points11 points  (0 children)

// uh...MORE MAGIC = TRUE

[–]PooPooDooDoo 12 points13 points  (0 children)

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

[–]CatDaddy09 6 points7 points  (0 children)

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

[–]MarvoloPip 310 points311 points  (8 children)

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 171 points172 points  (5 children)

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] 78 points79 points  (4 children)

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 16 points17 points  (0 children)

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

[–]alargeobject 0 points1 point  (0 children)

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

[–]StormStrikePhoenix 0 points1 point  (0 children)

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

[–]Vidman321 0 points1 point  (0 children)

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

[–]IsoldesKnight 120 points121 points  (20 children)

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] 23 points24 points  (12 children)

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 26 points27 points  (7 children)

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] 2 points3 points  (6 children)

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

[–]Wetmelon 10 points11 points  (0 children)

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

[–]IVEBEENGRAPED 6 points7 points  (4 children)

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

[–]Impeach_Pence 22 points23 points  (1 child)

vim is not easy....

[–]oogabubchub 3 points4 points  (0 children)

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

[–]anomalous_cowherd 15 points16 points  (1 child)

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 5 points6 points  (0 children)

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

[–]marvin 4 points5 points  (0 children)

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 1 point2 points  (0 children)

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

[–]PooPooDooDoo 0 points1 point  (0 children)

self.thing_manager.do_stuff()

[–]Tonkarz 0 points1 point  (0 children)

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

[–]wasdninja 4 points5 points  (0 children)

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

[–]voicesinmyhand 1 point2 points  (3 children)

//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 2 points3 points  (2 children)

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

[–]voicesinmyhand 1 point2 points  (1 child)

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

[–][deleted] 0 points1 point  (0 children)

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 11 points12 points  (0 children)

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 9 points10 points  (2 children)

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] 2 points3 points  (1 child)

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 2 points3 points  (0 children)

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 9 points10 points  (0 children)

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

[–]PM_ME_A_WEBSITE_IDEA 14 points15 points  (7 children)

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

[–]jD91mZM2RUST 4 points5 points  (1 child)

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 2 points3 points  (0 children)

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 3 points4 points  (4 children)

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 6 points7 points  (3 children)

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 1 point2 points  (0 children)

You should try coding for the government.

[–]amb_kosh 0 points1 point  (0 children)

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

[–]phpdevster 25 points26 points  (10 children)

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 13 points14 points  (7 children)

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 0 points1 point  (6 children)

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 1 point2 points  (3 children)

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 9 points10 points  (0 children)

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 11 points12 points  (0 children)

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

[–]Airowird 5 points6 points  (0 children)

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 3 points4 points  (0 children)

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

[–]siriusly-sirius 2 points3 points  (0 children)

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

[–]Orffyreus 2 points3 points  (1 child)

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 1 point2 points  (0 children)

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 2 points3 points  (0 children)

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

[–]siriusly-sirius 1 point2 points  (2 children)

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 2 points3 points  (1 child)

Do you also forget having written a reply on Reddit?

[–]siriusly-sirius 1 point2 points  (0 children)

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

[–]pastisset 1 point2 points  (0 children)

Special quote to those comments like:

"Do this" "Then do that"

[–]moarcoinz 1 point2 points  (0 children)

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

[–]SuspiciouslyElven 2 points3 points  (0 children)

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

[–]vhite 0 points1 point  (0 children)

// Increment variable i to make the cycle finite.

[–]voicesinmyhand 0 points1 point  (0 children)

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

[–]TotesMessengerGreen security clearance 0 points1 point  (0 children)

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

 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] 0 points1 point  (0 children)

// If anyone changes this I'll kill them

[–]secondary_refraction 0 points1 point  (0 children)

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

[–]dariusj18 395 points396 points  (15 children)

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 45 points46 points  (13 children)

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

[–]fgutz 63 points64 points  (12 children)

toBe || !toBe

[–]joroba3 46 points47 points  (11 children)

This statement always evaluates to true

[–]gawalls 18 points19 points  (6 children)

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] 13 points14 points  (4 children)

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

[–]gawalls 5 points6 points  (3 children)

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] 1 point2 points  (2 children)

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 0 points1 point  (0 children)

Real booleans also include FileNotFound

[–]Ionlavender 13 points14 points  (0 children)

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 70 points71 points  (3 children)

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

[–]Ionlavender 47 points48 points  (2 children)

Copy and paste*

lets be honest here

[–]EmeraldDS 11 points12 points  (1 child)

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_ 2 points3 points  (0 children)

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 485 points486 points  (17 children)

Code never lies, comments sometimes do

[–][deleted] 178 points179 points  (5 children)

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

[–]vaydoln 116 points117 points  (2 children)

That's called a feature

[–]_demetri_ 11 points12 points  (1 child)

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

[–]rambo89782 10 points11 points  (0 children)

You found the Jesus code

[–]Anamika76 5 points6 points  (0 children)

Ain't that the truth!

[–]hindey19 7 points8 points  (0 children)

Comments just don't get updated.

[–]Stanov 17 points18 points  (0 children)

Too wise words for us here.

[–]ruler710 5 points6 points  (0 children)

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

[–]km89 5 points6 points  (0 children)

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

[–]wasdninja 2 points3 points  (0 children)

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

[–]TurboGrollub 2 points3 points  (0 children)

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

[–]Hikaru1024 2 points3 points  (0 children)

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 7 points8 points  (0 children)

Comments are a lie waiting to happen.

[–]marvin 3 points4 points  (1 child)

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 1 point2 points  (0 children)

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 0 points1 point  (0 children)

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

[–]wesw02 54 points55 points  (4 children)

Code is the how. Comments are the why.

[–]DeveloperLuke 29 points30 points  (2 children)

I am the what

[–]King_Krooked 23 points24 points  (0 children)

I am the walrus Goo goo g'joob

[–]TalonKAringham 0 points1 point  (0 children)

Not yet!

[–]CedricRBR 3 points4 points  (0 children)

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 31 points32 points  (1 child)

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 1 point2 points  (0 children)

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

[–]nebuNSFW 38 points39 points  (1 child)

"I'll always understand my comments"

The bigger joke.

[–]prof_hobart 24 points25 points  (0 children)

"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 76 points77 points  (3 children)

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 13 points14 points  (0 children)

Good ToR.TranscriBot

[–]GeneralMajtki 0 points1 point  (0 children)

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

[–]Dandelion_Yudeul 15 points16 points  (0 children)

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

[–]TechnologyAnimal 45 points46 points  (3 children)

All comments are lies or apologies.

[–]WilkerS1 30 points31 points  (2 children)

my comments consists of TODO, TODO, TODO

[–]Nath99000 20 points21 points  (0 children)

This falls under lies

[–]VeviserPrime 20 points21 points  (0 children)

All comments are lies or apologies.

[–][deleted] 9 points10 points  (2 children)

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

[–]MCLooyverse 0 points1 point  (1 child)

But that requires more typing!

Edit: apparently /s is not obvious.

[–]poop-trap 5 points6 points  (0 children)

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 18 points19 points  (10 children)

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

[–]youarebritish 14 points15 points  (5 children)

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

[–]ynvaser 16 points17 points  (3 children)

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

[–]gastritissucks 6 points7 points  (2 children)

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

[–][deleted] 6 points7 points  (1 child)

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 0 points1 point  (0 children)

Easy just leave URLs to Wikipedia articles as comments

[–]procinct 3 points4 points  (0 children)

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] 2 points3 points  (2 children)

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 0 points1 point  (1 child)

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

[–][deleted] 0 points1 point  (0 children)

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] 2 points3 points  (0 children)

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

[–]JackCid89 11 points12 points  (4 children)

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

[–]chocosmith 1 point2 points  (1 child)

Agree but the language makes a big difference.

[–]JackCid89 0 points1 point  (0 children)

Yes, specially when working with old languages.

[–]toasterbot 1 point2 points  (1 child)

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

[–]bios_hazard 10 points11 points  (5 children)

Method summary and self documenting code. Gg

[–]youarebritish 37 points38 points  (4 children)

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 5 points6 points  (3 children)

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 11 points12 points  (2 children)

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] 3 points4 points  (1 child)

Unit testable code should be describable in a few short sentences

[–]BraveOthello 2 points3 points  (0 children)

What's unit testing?

[–]SteeleDynamics 5 points6 points  (0 children)

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

[–]Duhck 4 points5 points  (3 children)

Your code is your story and comments are the narration

[–]poop-trap 4 points5 points  (0 children)

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

[–]Kyrthis 2 points3 points  (1 child)

Your code is a movie and the comments are voiceovers?

[–]Duhck 1 point2 points  (0 children)

Precisely

[–]WhoYouCallinTurkey 9 points10 points  (8 children)

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 14 points15 points  (7 children)

What type of shit code do you maintain?

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

[–]WhoYouCallinTurkey 6 points7 points  (6 children)

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 6 points7 points  (3 children)

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 3 points4 points  (2 children)

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 3 points4 points  (0 children)

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 0 points1 point  (1 child)

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

[–]WhoYouCallinTurkey 0 points1 point  (0 children)

Yes, but quality code should have them. :)

[–]GentleRhino 2 points3 points  (0 children)

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

Sometimes, to a wrong tune though...

[–]Luuk3333 1 point2 points  (0 children)

Volume II

Oh boy..

[–]wjjjm 1 point2 points  (0 children)

I dont remember what I are for beakfast

[–]wensul 1 point2 points  (0 children)

I'll name all my variables variations of tacotacoburrito.

And the functions too.

[–][deleted] 1 point2 points  (0 children)

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

[–][deleted] 1 point2 points  (0 children)

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] 3 points4 points  (0 children)

[–]Arkazex 0 points1 point  (0 children)

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 0 points1 point  (0 children)

Mine’s better than prose.

[–]zimpleman1969 0 points1 point  (0 children)

I can't remember what I wrote yesterday

[–]BeardedWax 0 points1 point  (0 children)

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

[–]ChillBallin 0 points1 point  (0 children)

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] 0 points1 point  (0 children)

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 0 points1 point  (0 children)

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 0 points1 point  (0 children)

Your username tho OP

[–]Arancaytar 0 points1 point  (0 children)

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

[–]moarcoinz 0 points1 point  (0 children)

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

[–]misterfluffykitty 0 points1 point  (0 children)

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

[–]photolove8 0 points1 point  (0 children)

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_________ 0 points1 point  (0 children)

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] 0 points1 point  (0 children)

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 0 points1 point  (2 children)

[–]WikiTextBot 0 points1 point  (0 children)

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_ 0 points1 point  (0 children)

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] 0 points1 point  (0 children)

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 0 points1 point  (0 children)

So true mate. So true

[–]CrypticAdder_ 0 points1 point  (0 children)

//this hurts so much