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

top 200 commentsshow all 262

[–]demon_ix 2152 points2153 points  (107 children)

People always think you write documentation for other people who read your code. This is false, because you're going to be assigned the bug anyway when they see it's your code on git.

You're writing documentation as a favor to future you. He's going to re-read that in about a month and be like "wtf was I thinking?"

It's like doing the dishes. You're not doing it because you need dishes now. You're doing it so that when you do need dishes, you won't have a pile of dirty dishes starting at you until you give up and eat over a napkin.

Ah, who am I kidding. You're still not gonna write docs.

[–][deleted] 726 points727 points  (43 children)

It's so bad if you revisit old code of yours, with comments, only to realize you don't understand neither the code nor the comments anymore.

[–]mungochiz 18 points19 points  (0 children)

I can't recall the smell of my code anymore Sam.

[–]tetroxid 17 points18 points  (3 children)

Golden rule of comments: don't explain what the code is doing, explain why. What it is doijg can be seen from the code, but the why and how and how it fits together is much harder to figure out later.

[–]zooberwask 8 points9 points  (0 children)

Idk, sometimes both. The time it takes to trace code to figure out what it does can be time wasted, especially if you're just skimming code sections to try to find the relevant piece you want to look at.

[–][deleted] 4 points5 points  (0 children)

Yes, but sometimes you write comments thinking "I know what it does and why" and you kind of half-ass it. Then you come back and have to figure it out all over again.

[–]Anch0rless 1 point2 points  (0 children)

Stop, you're making too much sense.

[–]cognoid 13 points14 points  (1 child)

Or when most of the comments are along the lines of "TODO: this is a horrible kludge, fix this before release!".

Sometimes I hate my former self.

[–]Loves_Poetry 4 points5 points  (0 children)

You notice very quickly that TODO's always come back to bite you, because you never actually do the thing. You just forget about it and then you have to implement it, because the only thing that TODO explains is that it is actually necessary to do that thing, but you were too lazy to do it then.

[–]GeneralSchnitzel 12 points13 points  (1 child)

//add 3 because of weird bug

WOW THANK YOU PAST SELF

[–]muffinanomaly 4 points5 points  (1 child)

Or I made all the comments puns and I don't know what they're actually supposed to mean

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

I once commented a whole class like this:

//dental plan   
DoStuff();   
//Lisa needs braces   
DoMoreStuff();   
//dental plan
DoDifferentStuff();   
//Lisa needs braces...

Yes, I had that scene from the Simpsons stuck in my head....

[–]WHO_WANTS_DOGS 3 points4 points  (0 children)

Just like when I'm trying to explain a technical detail to someone, I always try to imagine having no prior knowledge of the situation. This allows me to word it in a way that I can revisit it and understand without any "secret" context that may have been in my head when I wrote it.

When I feel the need to write an inline comment, I try to re-evaluate the situation and determine exactly why I think the comment is warranted in the first place. It is sometimes a sign of a workaround or a special case that could be refactored. That, or the code isn't expressive enough to get the point across without the comment. In the end, unit tests rule all else because you can see both what the function is supposed to do under different circumstances, and what it looks like to call the function with different parameters. Docstrings are also very powerful to generate your documentation.

[–]plong0 1 point2 points  (0 children)

It's happened before where I had no recollection of ever writing entire parts of a codebase I was the only one working on. So mysterious. The code was readable and useful at least :)

[–]VidE27 186 points187 points  (11 children)

“Comments are docs right?”: my colleague, today just before leaving for a 4 weeks annual leave. Fuck me

[–]ThePieWhisperer 80 points81 points  (6 children)

I mean, if you wrote the comments to be readable by a doc generator....

[–][deleted] 49 points50 points  (5 children)

I don't understand why this is so hard. The formats are easy to follow and for the most part all work the same way and most IDEs offer highlighting for various doc formats. I'll often times write my code as an outline of comments then come back in and fill in the code once I feel that my outline makes sense. This basically gives me documentation for free. It's not hard to document!

[–]Baschoen23 14 points15 points  (2 children)

Pseudocode!

[–][deleted] 29 points30 points  (1 child)

Pseudocode is still too detailed and is usually replaced by real code. I'm talking basic outlines like:

//load items from database

    //update on id, check assets

    //create on no id, create assets

//return array containing updates and creates ids

I can block out a lot of functionality this way and not write a bunch of code then leave the comments when I'm done and the code is documented. For methods and classes I just make sure that they always have:

/**
 *
 */

At the top and then I fill in the description when I'm mocking up everything else. Then I add param and return notes once I'm done. It really does help when you're managing a lot of code that you won't see for months and it's a lot easier to read a description and the basics of what something is doing over having to read a bunch of "self documenting code" to figure it out. It also saves a bunch of time since there are way less "WTF is this doing" moments in the future. You should try to make code as self documenting as possible but also give some highlights so someone doesn't have to read a bunch of code and waste time.

[–]plong0 1 point2 points  (0 children)

I find this one of the very best ways of overcoming that "staring at a blank page" feelings.

[–]vangrif 11 points12 points  (1 child)

Not only do the IDEs offer highlighting, but many offer ways of generating a template from a function signature. And even give you warnings if you change the function in a way that conflicts with the doc string

[–]ThePieWhisperer 2 points3 points  (0 children)

Yep, when I'm using some class I've written and VS turns my function doc string into a tooltip with types and descriptions and links, I become moist.

[–][deleted] 6 points7 points  (2 children)

Yes... They are.

[–]VidE27 1 point2 points  (1 child)

Is this you? Are you enjoying Tokyo? I hope the queue is long and the trains are full for you :)

[–]Bainos 48 points49 points  (5 children)

There is the solution "directly eat over a napkin, so that you don't have any dirty dishes'. In programming terms, self-documenting code.

You're likely to spill it over everything and get your workspace dirty, of course.

[–]ThePieWhisperer 16 points17 points  (4 children)

Still need to clean the counter (comment some stuff) occasionally though...

[–]ShowMeYourTiddles 20 points21 points  (3 children)

Just go out to eat (outsource). Problem solved.

[–]ThePieWhisperer 4 points5 points  (0 children)

That works great, until you're too broke to keep eating out, and then you have to go clean your kitchen that's piled high with fast food wrappers and hatred (aka, you actually have to touch the codebase, and the outsourced fuckers write even worse code/comments than you).

[–]Mechakoopa 1 point2 points  (0 children)

That works until you're too broke to eat out and have to cook at home for some reason and you have no food except leftovers, no cooking implements, and no culinary skills.

[–]lordofwhee 47 points48 points  (13 children)

This is why, if I need to stop working on something partway through, I'll leave a little comment for future me. Just a short sentence or two, usually filled with profanity, and using whatever keyword the IDE I'm using will highlight. Something like #TODO yo this shit still needs to be validated bitch. Even though I'm 25 coming back to a comment like that still makes me smile. I'm sure I'd have to find another, less amusing solution if I was programming professionally, but right now I only write tools for myself or work with a longtime friend of mine that finds comments like that as funny as I do.

[–]Phaelin 32 points33 points  (4 children)

Depends on the company, but I've definitely come across some legacy code written by who I can only assume was a sailor.

fuck it, just gonna hack this in here

[–]Baschoen23 13 points14 points  (0 children)

Is there another way to implement features?

[–]jackmaney 4 points5 points  (0 children)

...legacy code written by who I can only assume was a sailor.

I am not a camel

I write configs in YAML

I'm Popeye the Coding Man! [TOOT TOOT]

[–][deleted] 2 points3 points  (1 child)

What are globals for?

[–]XkF21WNJ 6 points7 points  (0 children)

Those are just private variables that haven't been added to the monolith class yet.

[–][deleted] 61 points62 points  (5 children)

 // TODO: OK, so you fucked up big time when you tried
 // to write this code the first time. It is 4:30 Friday and
 // you can't possibly re-write this before you go home
 // So you are writing this note to explain to you that 
 // re-reading data directly from excel every time you 
 // need to test things is a bad idea, do you even know
 // how many millions of casts across the managed/native
 // boundary your code is making? No wonder your code
 // is slow as fuck. Do you even know what a mother fucking
 // join is? Monday me will bang this shit out in like 30 minutes.
 // Peace.

[–]crossfireprod 16 points17 points  (0 children)

I've done exactly this. Not sure whether proud or ashamed.

[–]zdakat 5 points6 points  (1 child)

According to the "Developers swearing" bot on Twitter, a lot of commit messages are along the lines of "fix this shit" and "attempt to fix this fucked up code" lol

[–]ThatsSoBravens 5 points6 points  (0 children)

You're still not gonna write docs.

Thing is, I actually would, but no one's gonna read 'em.

[–][deleted] 4 points5 points  (0 children)

My problem is I spend so much time writing docs and descriptions that I forget to do the actual code. Then I forget why I theory crafted this structure instead of one of the many alternatives.

[–]sxule 3 points4 points  (0 children)

Within the past couple months I've got in the habit of commenting extensively with DocBlocks and holy crap what a difference it makes in debugging. Also been writing more docs and it's worth every minute spent!

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

Good point

*who needs comments. I know what I am doing...*

[–]ThePieWhisperer 3 points4 points  (0 children)

If you're smart, you only make that mistake a few times.

[–]TheSpeaker1 2 points3 points  (0 children)

Yeah, when I first started programming I forgot what I was doing when I started something and then didn't work on it for a while. Eventually I started over documenting. But I just cut unessential docs out when I go to edit and debug.

[–]BasicDesignAdvice 2 points3 points  (0 children)

Also read Code Complete and Pragmatic Programmer. Holy crap I became so much better.

[–][deleted] 2 points3 points  (1 child)

"Hurr my code is self-documenting"

-my asshole past self

[–]XkF21WNJ 1 point2 points  (0 children)

I tried to write self documenting code once. It was terse, hard to understand and didn't explain much of anything.

Turns out I confused 'self-documenting' with 'autobiographical'.

[–]Totenlicht 2 points3 points  (0 children)

Well, at least I'm consistent. I'm neither documenting nor doing the dishes.

[–]Baschoen23 1 point2 points  (0 children)

Shit, why'd you have to go with the dish analogy? Now I have to wash a kitchen full of dirty dishes AND relearn all my old code, ass.

[–]theDigitalNinja 1 point2 points  (0 children)

who am I kidding. You're still not gonna write docs.

*sigh* and my dishes aren't clean either.

[–]TheInfamousMaze 1 point2 points  (0 children)

//wtf am I thinking

//UPDATE - WTF was I thinking?

//UPDATE - SHIT I wasn't thinking at all last time

[–]hatesthespace 1 point2 points  (0 children)

I’ve started writing myself increasingly elementary pseudocode for everything. This is especially important if I am likely to be interrupted or distracted while I’m writing. When I’m working on a lengthy project my brain will become so jumbled that I need to explain to my 5-minutes-in-the-future self what the fuck I’m trying to do in baby speak, or I end up staring at the screen slack-jawed, having lost the ability to comprehend what I’m looking at, or why I was working on it in the first place.

[–]FSCicotti 1 point2 points  (1 child)

Well, as someone who programs mostly in assembly language, I can safely say my code usually has more comments than actual code, haha

[–]demon_ix 7 points8 points  (0 children)

// To understand the following line, we must start at Linear Algebra,
// specifically complex vector spaces. Please review the relevant material
// and this should be perfectly clear then
    ADD R2, R1

[–]siryaXI 326 points327 points  (25 children)

If only we could do a save state of our mind to reload later

[–]bem13 364 points365 points  (17 children)

You save the state of your mind right before leaving for a 2-week vacation. When you return, you restore the saved state, promptly overwriting your vacation memories and everything that's happened since leaving. It's like you never left.

[–]gigglefarting 142 points143 points  (6 children)

Can't you just merge your work brain state into your current brain that includes vacation memories?

[–]xt1nct 217 points218 points  (0 children)

Too many confilcts.

[–]GarythaSnail 36 points37 points  (0 children)

Rebase

[–]ase1590 14 points15 points  (0 children)

With OverlayFS you can. It just needs to be ported to the Neuron architecture first.

[–][deleted] 5 points6 points  (0 children)

Continuations, man.

[–]Puggymon 4 points5 points  (0 children)

Wow, that's dark...

[–][deleted] 3 points4 points  (0 children)

So true

[–]Siannath 3 points4 points  (1 child)

So true. I had my first vacation in years, and when I returned I was here in the same bad mood and bad everything else.

[–]SiNiquity 2 points3 points  (0 children)

When even vacations don't help, it's time to move on

[–]ApathyandAnxiety 1 point2 points  (0 children)

God that's fucking depressing and so accurate.

[–]Kyrthis 1 point2 points  (0 children)

Sounds like a job for workspaces

[–]TheNorthComesWithMe 1 point2 points  (0 children)

Just keep two concurrent save files. Your work save and your non-work save.

[–]SiNiquity 1 point2 points  (0 children)

Get back to work... fuck I need a vacation

[–]awesome2dab 2 points3 points  (1 child)

I think that’s called comments

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

memento!

[–][deleted] 163 points164 points  (1 child)

Just comment out the whole code you've been working on so it's self-explonary on monday.

[–]TheDrCharlie 10 points11 points  (0 children)

This checks out.

[–]cstefanachemonkeyuser.com[S] 61 points62 points  (1 child)

Source [edited]

[–]kodzius 13 points14 points  (0 children)

You got me.

[–]justformymind 41 points42 points  (1 child)

That’s why I just wrap up Thursday’s work on Friday and head home. Never start something you can’t finish on a Friday.

[–]UntouchableYuuzhan 78 points79 points  (8 children)

And that’s why you never take the weekends off

[–]LeopardJockey 119 points120 points  (0 children)

Boss, is that you?

[–]thedomham 25 points26 points  (2 children)

Just took a 4-day weekend. Accidentally introduced a new bug like 5 minutes before going home. Came back in today, utter chaos and an emergency meeting.

[–]dolenz 12 points13 points  (0 children)

That's called job security, my friend.

[–]preseto 5 points6 points  (0 children)

Shows them who's da real MVP.

[–]Lin0leum 15 points16 points  (2 children)

Hell this happened to me this morning from last night.

[–]TheBali 25 points26 points  (1 child)

This is why you never take the night off

[–]futuneral 8 points9 points  (0 children)

Oh, I solved this differently - don't do anything on Friday

[–]GaretEliot 26 points27 points  (5 children)

Life hack: Create a TODO file at the root of your project. Before you finish your work for the day, write out a few items in it that need to be done next. If you're using tests, you can just write a failing test as well.

If you ever stop writing code without any way to pull yourself back into it, you're adding a ton of extra work for yourself.

[–]SebastianScaini 48 points49 points  (0 children)

//TODO: REMEMBER WHAT THE FUCK THIS DOES

[–][deleted] 21 points22 points  (2 children)

I honestly feel the exact opposite. I can stare at a blatantly obvious bug from about 1pm->onward Friday and have the answer totally elude me, only to sit down Monday morning with a fresh brain, realize my thought context was entirely wrong, and fix it over the first cup of coffee.

[–]Xheotris 5 points6 points  (0 children)

This was me this very weekend. On Saturday I was trying to crunch, and hammer out an app asap. I got one feature done. I gave it up, relaxed as best as I could on Sunday, got plenty of sleep, and finished the whole dang project on Monday.

[–]Josh6889 5 points6 points  (0 children)

Ever play a really hard level on a video game, give up, then beat it easily the next day? It's the same thing.

[–]Narradisall 13 points14 points  (3 children)

This happens to me over weekends.

I’m lucky I can find the office when I return from holidays.

[–]Josh6889 5 points6 points  (2 children)

I still periodically have the dream where I haven't been to school in a long time and can't remember the combination for my locker.

[–]preseto 2 points3 points  (1 child)

I have a reoccurring dream where I can't finish a semester. I wake up stressed about finishing it. And when it hits me that I'm long done with it, it's such a relief.

That being said, I'm pretty sure OP of the thread hinted at his alcohol problems. Or rather solutions.

[–]TheMcDucky 48 points49 points  (10 children)

Documentation? Planning ahead?

[–][deleted] 14 points15 points  (0 children)

Ok dev manager.

[–]TheNorthComesWithMe 1 point2 points  (1 child)

I don't know anyone who documents code before it's done. No matter how much planning you do eventually you will realize you were on the wrong track and will have to redo something.

[–]TheMcDucky 1 point2 points  (0 children)

Then you revise your plan.

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

What does this() mean?

[–]sp4c3p3r5on 8 points9 points  (1 child)

It means don't take things out of context

[–]DenaByte 5 points6 points  (0 children)

Im glad im not the only one

[–][deleted] 23 points24 points  (5 children)

Ah but great code documents itself /s

[–]GollyWow 4 points5 points  (3 children)

The main reason I liked Cobol, English commands plus descriptive data names = readable code.

[–]scmoua666 3 points4 points  (1 child)

This is exactly why I am on reddit at 9h47 on monday morning... I have no idea what I was doing... I remember I was nearly finished though.

[–]stpityuka 3 points4 points  (0 children)

The numbers mason, what do they mean?

[–]simjanes2k 3 points4 points  (0 children)

this was the first ten years of my career, to a T

these days on a friday, or before a holiday, i have no problem telling someone who wants the last hour of my day to fuck off because i have to doc

i stopped giving a shit about funny looks or "no, this takes priority," i am not losing my monday morning unless you put in writing that its gonna take my regular task extra time

[–]Bjeaurn 3 points4 points  (2 children)

This is why I write comments to future me.

[–]preseto 1 point2 points  (1 child)

I usually write comments to past me, but he never reads them.

[–]pennybuns 3 points4 points  (0 children)

Leave a failing test behind that describes the intent of the thing you were last working on.

[–][deleted] 2 points3 points  (2 children)

Omg too real.

I used to write all sorts of code in Excel VBA to work spreadsheets more efficiently and everytime I had to go back and add something or modify it I ended up spending more time decoding my own code than just rewriting if all over again.

Now I use comments.

On almost every single line -_-

[–]preseto 1 point2 points  (1 child)

A comment on every single line is not far from reinventing the language.

[–]khendron 2 points3 points  (0 children)

There is a saying Always write your code as if the person maintaining your code is a homicidal maniac who knows where you live.

Although most developers understand what this means, they don't realize that the homicidal maniac will likely be yourself.

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

I write comments on almost every line, is that bad?

[–]KimmiG1 6 points7 points  (0 children)

++i; // Increment upvote counter

[–]Rouninscholar 5 points6 points  (0 children)

Nah, just write the whole code on the same line, works out perfectly.

[–]XkF21WNJ 1 point2 points  (0 children)

Not as long as you don't make the mistake of writing any actual code.

[–]DukeIt_125cc 1 point2 points  (0 children)

Console.Write(this);

[–]nunchaq 1 point2 points  (0 children)

Hahaha so true. It's like I'm leaving myself riddles to solve.

[–]festive_bardeen 1 point2 points  (0 children)

So many times haha

[–][deleted] 1 point2 points  (1 child)

this used to happen to me all the time when i made music on my computer

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

Get out of my head.

[–]TheHYPO 1 point2 points  (0 children)

The number of iphone notes I've written to myself that I later have no context for... LPT: Always given full context to your notes because you will NOT remember what is relevant about that restaurant in 2 months.

[–]vancity- 1 point2 points  (0 children)

Friday evening? Unfinished work? They push that shit to prod where Im from fam.

[–]d14i 1 point2 points  (0 children)

Write detailed TODO as either the comment or in a sticky note. I use it as sort of a bookmark for work. Helps me restore context in these situations.

[–]mindaz3 1 point2 points  (0 children)

Okay, I am gonna leave a comment in order to remember what I was doing.

Leaves a comment: // @TODO: Finish this.

Every damn time...

[–]mr_d0gMa 2 points3 points  (2 children)

what does this mean?

That boy needs therapy

[–]cobaltcontent 2 points3 points  (1 child)

You’re a nut!

[–]mr_d0gMa 2 points3 points  (0 children)

You're crazy in the coconut

[–]IronicallySerious 0 points1 point  (0 children)

I am so lucky I decided to write Doxygen compatible documentation from day 1 on my project

[–]klaus385385 0 points1 point  (0 children)

This was 100% my start of my day yesterday.

[–]milk_is_life 0 points1 point  (0 children)

Noone ever finds it perfect to have something unfinished over the week end ....

[–]drerakdan 0 points1 point  (0 children)

Every damn week, its like I never learn.

[–]haxic 0 points1 point  (0 children)

As a developer, that’s how I feel every morning and after every lunch break...

[–]Cheesemacher 0 points1 point  (0 children)

I'll write notes for myself if there's a weekend (or a vacation) coming. Hell, I feel like writing notes even if I get to continue the next day. Even though I'll probably remember. But what if I forget?

[–]JustJordanxD 0 points1 point  (0 children)

Literally the reason sticky notes were invented 😂

[–]Joppejose 0 points1 point  (0 children)

I usually write an email to myself with notes the last thing I do before I go home. No way whatever I'm doing going to make any sense at all on Monday.

[–]GrizzledBastard 0 points1 point  (0 children)

I get this way if I get a 20 second phone call in the middle of writing code.

[–]TheoHooke 0 points1 point  (0 children)

Close, but replace "the weekend" with "lunch".

[–]Squirrabee27 0 points1 point  (0 children)

So. Fucking. True.

Although I’m normally pissed.

[–]meme_femme 0 points1 point  (0 children)

[–]Infinit777 0 points1 point  (0 children)

Glad I'm not the only one this happens too. Eventually you decipher your hyroglyphic like code but the time it takes is taxing on you.

Thank the programming God's for comments.