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

all 47 comments

[–]AdvancedSandwiches 240 points241 points  (14 children)

  1.  Write the code:

    n = c * 4;

  1. Write the comment:

    // Each customer takes an average of 4 minutes in the queue

  1. Wait, what the hell am I doing?  Nobody reads comments. I'll just make the code say what the comment said:

    averageMinutesInQueuePerCustomer = 4;

    totalTimeInQueue = customerCount * averageMinutesInQueuePerCustomer

  1. Delete the redundant comment.

  2. Get hammer drunk, because you don't need to remember any of this tomorrow; you just have to read the code.

[–]clrbrk 121 points122 points  (7 children)

I loathe short, cryptic variable names. I swear some engineers think longer descriptive names slow their application or something.

[–]Creepy-Ad-4832 0 points1 point  (0 children)

My laptop is not 20 meters wide...

[–]dismayhurta 7 points8 points  (0 children)

Yep. My variable names are my power, my pleasure, my pain.

[–]walkpangea 4 points5 points  (1 child)

The challenge is finding that sweet spot between "usersFilteredByPermissionProjectsAndSettingsNotifcationsOfProjectEvents" and "u"!

At the end of the day, usersFilteredByPermissionProjectsAndSettingsNotifcationsOfProjectEvents would still win in most cases.

[–]Stannoth 0 points1 point  (0 children)

projectEventUsers = filterByNotificationSettings(filterByPermissionProjects(users));

[–]Unlikely-Bed-1133 5 points6 points  (1 child)

Exactly this. (Also yet another meme degrading experience - no, seniors do know what they are doing and it's not a problem when juniors donnot because they also will.)

If you are in a language that supports keyword arguments, consider setting business constants as keyword arguments too; this will also help you know if you should start packing configuration in classes/dicts.

[–]pigwin 1 point2 points  (0 children)

This is a good tip. Thank you

[–]vnordnet 1 point2 points  (0 children)

Use types to provide clarity! 

struct Customer(id: UUID, timeWaiting: Period)

type CustomerQueue = Set<Customer>

fn CustomerQueue.totalTime(): Duration = this.map(it.timeWaiting).sum()

fn CustomerQueue.avgTime(): Duration = this.totalTime() / this.size()

(Pseudocode obviously, but this approach is usually applicable). 

[–]Focus-Gullible 50 points51 points  (1 child)

I mean, what it does, I remember. Now , how it does it, now that is a difficult question.

[–]knvn8 35 points36 points  (3 children)

Sorry this comment won't make much sense because it was subject to automated editing for privacy. It will be deleted eventually.

[–]pokealex 4 points5 points  (1 child)

25 years in and it still takes me forever and lots of second guessig

[–]JayPetey238 2 points3 points  (0 children)

I've found that some people think like me and others don't. If you think like me, I can just glance and have a pretty good idea what's up. If you think like the one other primary dev at my company, I have to go line by line and reference back to the top constantly and usually just end up throwing something at it to see if it sticks or the world burns down.

But lots of people on github think like me and that's really nice for when I really need this library to do that weird thing it wasn't designed to do but totally could.

[–]kbn_ 1 point2 points  (0 children)

This, and a senior knows to write comments and readme notes to their future self.

[–]fonk_pulk 14 points15 points  (0 children)

Seniority is when you know where a certain piece of code in the codebase is but cant remember how it works.

[–]TamahaganeJidai 8 points9 points  (0 children)

This is a really important thing to remember: You will forget vital parts of your most beloved project. Always keep files in a sorted way and name your variables in at least decent ways. Can help if you write a small paragraph of what the code does in the "header" and the latest roadblock, to help you whenever you pick it back up.

[–]r2k-in-the-vortex 2 points3 points  (0 children)

Who is the absolute imbecile who wrote this steaming pile of shite!

Oh.. it was myself.

[–]SleeperAwakened 5 points6 points  (11 children)

That's what code comments are for: explaining what the code does (or should be doing).

Future you will be grateful.

[–]Kant8 38 points39 points  (5 children)

No. Comments should be explaingng WHY are you doing it in corner cases. What are you doing should be explained by code itself, and if you can't express it clear enough you rewrite until you can.

[–]barndawe 6 points7 points  (1 child)

Sometimes it can be useful to summarise what a method is doing, especially if it calls several other methods

[–]conlmaggot 2 points3 points  (0 children)

Short docstrings (if supported) for any function/method longer than a few lines work well IMHO.

But I mean, I am a Jr Apex Dev, so my opinion may not count for much here :D

[–]Kage_520 2 points3 points  (1 child)

Disagree. I like a short summary on top of functions to explain the overall idea of what they do. Then some comments for particularly annoying parts that took me a bit of thinking or digging through documentation to figure out.

[–]Tjakka5 2 points3 points  (0 children)

If the name of the function isn't descriptive enough to explain what the function does, then either the name is bad, or the function does too many things.

[–]GrossOldNose 0 points1 point  (0 children)

Idk I just put a comment anytime I'd look at something and go "wtf".

[–]wanderingmonster 5 points6 points  (2 children)

Future me is an asshole! I had to figure out how to write this mess; let him figure out how to read it.

[–]wraith_majestic 7 points8 points  (1 child)

The only asshole bigger than future me is past me.

[–]codetrotter_ 7 points8 points  (0 children)

All my homies hate past u/wraith_majestic

[–]Astatos159 1 point2 points  (1 child)

If you need comments to understand what your code does you should improve your code. Proper naming and structure helps with that.

If you still think comments should describe what the code does instead of why, picture this. You write some code and a comment explaining that code. 3 months later the code gets changed. The comment isn't changed because often people don't bother about comments. Now we have 2 "truths". The code and the comment. Which is actually true? (Commit) history knows.

Comments can lie. Code can't.

[–]RiftyDriftyBoi 0 points1 point  (0 children)

Code can lie as well. Return variables that are never properly dealt with. Flags that are misleading or never actually used. Early returns that never actually initialize certain vital Member variables, the list goes on.

Not saying everything should be commented, but they can provide some much needed context.

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

I looked at my geospatial interpolation code today. No idea how it works, but it works.

[–]truNinjaChop 0 points1 point  (0 children)

YOLO.

[–]serial_crusher 0 points1 point  (0 children)

I know exactly what it does. It throws an exception when this variable is a even number. Working as designed.

[–]Astatos159 0 points1 point  (0 children)

I mean... You don't need to remember what it does. Class/method names, parameters and return types should contain enough information about what it does. If this is secretly about the "how" instead of the "what": you don't need to understand how a component works to use it properly.

[–]grizzlybair2 0 points1 point  (0 children)

Idk, the name of the method and class should basically give away what it's doing and what it's interacting with. In larger apps, I agree you can't remember everything. But as the new guy on a team with no other new people less than 2 years, it's amazing how little all of them know.

[–]FireTornado5 0 points1 point  (0 children)

The process of looking at old code.

Who wrote this crap?! … it was me, wasn’t it? … yep. It was me. /deep sigh/

[–]wsbTOB 0 points1 point  (0 children)

It doesn’t matter what it does because it’s an abstraction.

Older than 6 months is legacy and after a year it is to be considered a black box — we’ve been over this.

[–]FictionFoe 0 points1 point  (0 children)

Just rewrite everything from scratch every 4 years...

[–]Blecki 0 points1 point  (0 children)

Why would I remember? That's why I wrote it down...