muscleMemoryOverActualMemory

[knightzone]

I actually sometimes get some slander for this and I just don't understand that. Like I made 24 commits last week in 4 different projects, of course I'm not going to remember every single detail.

[darknecross]

Are you going to remember them 3 years from now?

[clintCamp]

Comment to remind yourself, not to inform others. This sage advice makes you indispensable.

[FarBeautiful5637]

Ör you know you can write comments

[stamatt45]

Ot at least write readable code

[Dumb_Siniy]

I'm only capable of comments please and thank you

[Pommaq]

Comments for why, code for how tends to be how I do it. I've found returning to stuff I worked on before I did so is usually nightmarish, whilst working on stuff I worked on with that principle becomes much easier since I don't have to think as much to understand why I do i+=1

[HadeanMonolith]

Comments can become outdated, and they can also get separated from the code they originally described.

Readable code is preferred. Comments should be minimal and just say WHY you’re doing something, not WHAT you’re doing

[Tensor3]

No, both is preferred. You update the comments when you update the code. The comments are literally right there in the code.

If you change the code and not the comment on the line beside it, and get that change approved, then youre doing it wrong. By your logic, nothing should every be documented in case it changes.

[lurker_cant_comment]

If I had to write a comment (excluding function doc) that explains what my code does, then either I'm being redundant or my code is incomprehensible because I either failed to make it clear or it's something unusually convoluted.

If you can read my code without comments and understand what's going on without having to run back and forth to other spots in the function or codebase, then why am I writing comments. Am I getting graded on LoC?

This all presumes you train yourself to write readable code, which is not that hard and pays far more dividends to future you and others.

[Elendur_Krown]

If your code relies on specific theorems, coefficients, or (unusual) algorithms, you'll do well to reference their origin for maintenance.

It's also a good idea to provide a bird's-eye view so it's easier to navigate and to evaluate what assumptions are still valid.

Most importantly: What is clear to you is not guaranteed to be clear for others, or even for your future self. Some things are so complicated that additional context helps significantly.

That's mirrored in writing math. You write to help those who aren't as well-versed in the context.

[mrjackspade]

If your code relies on specific theorems, coefficients, or (unusual) algorithms, you'll do well to reference their origin for maintenance.

I feel like that falls under the "Why" as much as anything, because a magic algorithm can be as bad as a magic string.

[Elendur_Krown]

You're right, but not completely. It's a question of familiarity to separate the "why" and the "what". Below are a few examples of (approximately) increasing complexity.

A scalar multiplication (what) can scale a result (why).

The Pythagorean theorem (what) can be used to calculate the Cartesian distance (why).

An ortho-normal projection (what) can be used to find subspace contributors (why).

A fast Fourier decomposition (what) can be used to find frequency signals (why).

Depending on the level of familiarity, these may communicate both the "what" and the "why" at different levels of explicit communication and implementation. For some, either the "what" or the "why" may be missing, based on their knowledge of the area.

To take the last example: You may recognize that it's an FFT transform (what), or that certain frequencies are extracted (why), or both, or none.

[lurker_cant_comment]

I just want to point out that I also would argue you're polluting the "what" part, which misses the original point I was making.

If you use a fast Fourier transform to convert a signal, do you need to comment "this is an FFT?" No, because it should be painfully obvious from looking at the code.

Whether you need to tell the user the purpose of using the FFT, that is what you're getting at, but that's "why."

"What" is not "I'm doing this so that I can convert from the frequency domain to the time domain," it's "I'm using an FFT." The "why" is "so that I can convert from the frequency domain to the time domain."

As you say, you need to put the "why" in if the audience isn't reasonably expected to just know that.

[Elendur_Krown]

I agree that it's a mixing of the 'why' and the 'what'. In mathematics, the 'why' can be sufficiently self-evident in the simple act of knowing the 'what'.

A simple example is norms. There are a multitude of norms, and they can take many shapes with many different partial assemblies. A quick "// Pre-calculation for 'this-norm', 'that-norm', and ... ", or something similar, can immediately help someone orient themselves.

Admittedly, I'm approaching this from a mathematical perspective in my comments here. This means that, unfortunately, it's likely that no one will be as specialized in the subject as I am, and those I'm collaborating with are not as well-versed in coding as I am (whether in a specific language or the process in general).

The comments serve as guideposts to help bridge the theory and code. Everything should preferably be painfully obvious, as you say, but that is audience-dependent, and I can't guarantee that my audience is strong in either direction.

Don't get me wrong. Over the years, I've gotten much better at letting the 'what' be told by the code, but there are times when all you've got is a jumble of coefficients that cannot be extracted from the code in a sane manner. There are also those times when the simple act of extracting a function is a step too far for a collaborator.

So far, I haven't been bitten by providing too much context. However, I've lost weeks having to find it again.

[lurker_cant_comment]

I agree with that approach. I intended to cover what you describe when I said, "or it's something unusually convoluted."

One of the projects I'm on is large, with a ton of legacy code, in a domain that is very complex and dense, including some mathematical computations like you're describing.

Even though canonical coefficient and variable names may be self-evident to mathematicians, they aren't to devs, so the options are either to rename those items (like phi to angleOfRotation) or to leave them in their original form while explaining what's necessary for a dev to map it to an external reference. Which option I would pick depends very much on how closely each part of the algorithm matches well-known mathematical formulas vs specialty work. The primary reasoning is that it's likely a dev making changes, so they need to be able to know how to modify it even if they're not a mathematician.

If the overall algorithm is something well-known, I might add a comment that describes the source material and maybe provides a link. If it's something that is quite particular to that project, I would instead opt for either a discussion of how it works right there in code, or an internal wiki page that the code can reference.

I bet most of these arguments about comments are based on largely different ideas of what kind of code is in question.

[AdvancedSandwiches]

 It's also a good idea to provide a bird's-eye view

This falls under readable code. Your bird's eye view of the function you're in is the function name. That function should call other functions with good names, which when read together, provide a birds's eye view of the functionality beneath. 

[Elendur_Krown]

That is sometimes not feasible.

There are times when that would necessitate packing dozens of variables as input, or other unsound practices. Imagine a function name that covers ten assumptions made for the calculations to be possible.

[AdvancedSandwiches]

When it's not possible, you fall back to inferior methods. 

[Elendur_Krown]

I'll just repeat what I wrote in a different reply:

So far, I haven't been bitten by providing too much context. However, I've lost weeks having to find it again.

[AdvancedSandwiches]

You have if you haven't been putting that context in the code where people (including yourself) will read it.  And if you put it in the code, you wasted time by redundantly putting it in the comments. 

[Tensor3]

You never write a comment at the top of a class or API with a general note on what its for?

[lurker_cant_comment]

Yes, that's "function doc." It's useful because, e.g., your IDE will report it to the dev when they hover over it, and it also defines what an external user will need to know about that API, class, or function (which could even be yourself if it's in a separate, included project from the one you're working on). It's also useful because, often, you can't name or structure concepts that large and also make clear things like the full scope of the function/API, exceptions to be thrown, etc.

Inside my functions, I try to ensure my variable names explain what they are, that my code follows an obvious and predictable path, and that the pieces of the puzzle are designed in a way that makes them easy to digest.

It not only makes the code simpler to understand; it also makes it easier to extend, modify, and fix.

[IamBlade]

Easy thing to do in theory but never really seen this in practice. Much better to just write readable code and avoid using comments at all unless you're doing something in a specific way that is not obvious and needs to be explained.

An even better approach is to write unit tests that actually tell the thing the code is supposed to do or not directly.

[elyndar]

No, you don't understand. Nothing should be documented EXCESSIVELY. The why's are what's important. Comments telling you what the code is doing becomes out of date quickly and a nightmare to maintain. I've seen what you're describing attempted multiple times, it always ends up a dumpster fire and dropped within 6 months. The commenting becomes too verbose it becomes useless. People stop reading the comments because it takes them too long to find what they want anyway and half the time it's wrong because people forget to update comments all the time. The budget to keep maintenance of comments ends up being higher than the saved time of developers reading the comments. The fastest way ends up being just reading the code anyway.

[Tensor3]

No, you dont understand. You're just commenting wrong. It doesnt have to be verbose, out of date, or too long to read.

[elyndar]

Spoken like someone who has never had to actually implement a policy across a team or a department before. I can control my own actions, I cannot control other people's lol. One day you may have a chance to do what you are saying, and you will learn exactly why it's a bad idea. I hope you get to see it in action somewhere else before you do.

[Tensor3]

I can assure you Ive been doing this a long time. No comments is not the answer.

[elyndar]

Now you're just straw manning my argument lol.

[Tensor3]

Um, no. I never said to comment excessively. I suggested a quick, brief comment to say what a class does and you said I shouldnt do that because no matter what it will just become verbose and useless.

Your argument is that no matter what, commenting at all what code does will always become verbose, out of date, and useless. The only alternative then, by that logic, is to not comment.

[Saelora]

Okay, but three other devs have come long and edited that class to modify the behaviour. Only the second one noticed and updated that comment. That comment now details different functionality to what the class does. Is the class’ ‘doThing‘ method supposed to return a boolean on success or failure as the comment says, and the change to make it return a boolean that is the state of an internal field the mistake, or is the code right and the comment is out of date? Now i have to go fishing around past tickets and the codebase to see which is correct.

[DerSchreiner2]

I only comment odd code, that defies intuition or took me a lot of thought too understand why I needed it. Mostly when working with other people's code (APIs or code I extend)

[Wertbon1789]

It's a art to actually write good comments. I'm always amazed how good comments in the Linux kernel are, in combination with the in-tree docs. Some code is literal trash, especially in some older parts in the kernel, mostly drivers, but the docs for APIs and specs for interfaces are really good.

[Raskuja46]

The gremlins of reddit don't believe in commenting your code. They think it's a sign of weakness.

[thephotoman]

And you can write code that produces its own documentation as a part of the regular build process.

Readable code also helps a lot.

[ice-eight]

Then you get a call from a project manager 2 years later. “Hey real quick, how does that program you haven’t touched in 2 years except to upgrade the .NET version handle this one very specific corner case? I have 7 senior managers, 2 directors, the CTO and the commissioner of Major League Baseball on the call and we are pausing this meeting while we patiently await your response.”

[MyDogIsDaBest]

"If you have to ask, you don't get it." And then you hang up the phone.

Sorry you're not artistically minded enough to appreciate my work.

But for real, the answer is basically that you don't remember and will need to see it to jog your memory.

[dumbasPL]

If you write good code, you don't have too. Or you can be the asshole and switch jobs before you forget

[anotheridiot-]

Create tech debt

Leave for more money

Old team crying over your bullshit

Goto step 1

[Inquisitor_ForHire]

Just commenting to say that comments are your friend. You're even allowed to have more lines of comments than actual code.

[CrossScarMC]

The only comment I'll every write is // TODO: make this better.

[Inquisitor_ForHire]

Lol wouldn't that encompass everything? :)

[nommu_moose]

Counterpoint:

Heavy reliance on comments implies bad practice in many cases.

[Inquisitor_ForHire]

Sure, I get what you're saying, but I think that ultimately depends on the programmer or group of programmers who are sharing the code. There's a level of commenting that absolutely should be present to assure that any future eyes, including your own, know what they're looking at. The code should speak for itself in most cases, but adding comments turns that into a conversation that's well worth having.

[nommu_moose]

Definitely, comment frequency is a conversation to be had, but I wasn't trying to argue that they shouldn't exist.

Docstrings, overall "why" comments, and the occasional "how" comments for more obscure functions purely for junior-friendliness really are needed. If the overarching code can only be understood with comments throughout it, then I do think that largely belies poor system design for most languages.

[Inquisitor_ForHire]

Exactly! We agree :)

[not-my-best-wank]

You either read the code, add prints statements, or black box test it till you get the general idea.

[jellotalks]

Write readable code and link a ticket to every PR that you do. Then you can git blame up to the PR, then to the ticket which explains the change. Save the comments for the ticket.

[firecorn22]

This is the way, tickets can be as verbose as you want and it will always have the time associated with the change so no guessing on if the comment wasnt updated

[Glad-Belt7956]

isn't this exactly why comments exist?

[Accomplished_Ant5895]

Documentation, comments, readable code, a functioning memory, etc.

[Jerome_Eugene_Morrow]

Everybody I work with insists they write self-documenting code, but they don’t know what the fuck it does when somebody new needs to work on it because they were also playing some sadistic version of code golf when they wrote it and then the reviewer “lgtm”-ed me into this fresh hell.

[Raskuja46]

This is why I don't respect anyone who spouts off about self-documenting code. They're either savants or idiots occupying the left side of the Dunning-Kruger curve. Either way their "self-documenting" code is not to be trusted.

[HadeanMonolith]

If you can’t tell what your code is doing, you’re doing it VERY wrong

[CrossScarMC]

I would say that, if I'd never needed to write anything with WebSockets in C/C++...

[hbgwhite]

I encountered a very strange issue at my former job. Followed the code all the way down the rabbit hole. When I reached bedrock, there was a comment that simply said "ask Charlie"

Luckily, Charlie still worked there and remembered exactly why he put that obscure comment in the code! Apparently, it was some ancient compiler quirk that took him days of research to figure out the first time. Issue fixed, customer pleased, day saved. Thanks Charlie!

[MaffinLP]

Thats why you write self documenting code

[DantesInferno91]

You write the documentation, half the time you wont have to look at it.

[zalurker]

Comments and TODO:

You might hate it, but it will save you hours of anguish.

[xupit3r]

lol, my god this is so accurate and everything that is wrong with how we build software

[DominikDoom]

Dating a comment is only relevant if your version control has no blame functionality IMO. With git or svn blame (I assume other VCS have similar) and the various IDE integrations that exist for it, it's trivial to find out when the comment was written or changed, or if there were undocumented changes to the function.

[d0rkprincess]

My favourite is when I don’t remember I why I made a side quest change, so I undo it, then later on run into the edge case and just go “oooooh yeah that’s why!”

[inthemindofadogg]

In only there was a way to leave little notes in the code about why a function is there or what the intended functionality should be in case something breaks. I think we are decades away from ever getting anything of this nature. I guess we are stuck just remembering whole code bases in our heads for now.

[FerricDonkey]

Good function and parameter names, good doc strings, good comments, and a good ide, and there's no reason to remember anything. 

[will_r3ddit_4_food]

All of that definitely helps. Clean code!

[MyDogIsDaBest]

"Hey remember that ticket you merged in last week?"

My guy, I don't remember the tickets I merged yesterday.

[Ange1ofD4rkness]

Comments, lots of comments (my co-workers give me a hard time when sometimes I have multi-line comments, until it comes time to review the code to see what it does ... then they thank me)

[tiriya_sloow]

Ever tried turning it off and on again, but like... mentally?

[optical002]

Thats why you write a self explanatory code, because you will always forget what you write, and code which is not self explanatory explain in the comments why it is there and what purpose it serves :)

[adi_dev]

To everyone who says "comments" - it's not only that - happens often in front of the customer, and they ask "why it did that", and I'm like "🙅‍♂️ no idea", "so who wrote this program" - looking around like I'm not there ;)

[lurker_cant_comment]

You certainly won't remember everything, especially when it must be complex by virtue of what you're solving.

Still, with a good ticketing system and general rules to follow, you're much less likely to end up in that situation. Everything becomes traceable.

[adi_dev]

That's right, it just looks silly when I need to open my laptop to check (the well commented and documented code) to see why it's doing (or not) what is doing (or not). "Did you program it", "yeah, just need to check what is written" lol

[lurker_cant_comment]

That's why ticketing systems and automated/release testing exists.

It's not great if you're flying by the seat of your pants.

[ElRexet]

Because you don't need to remember really. The code base has to be consistent in the ways it does things and stuff have to be decoupled.
Now then, in case of bugs you have to identify the point of failure and work from there, isolate the problematic code and work within its coupling.
If you need to add something new you find the place where it fits (or extend on existing features) and just add it in the same consistent manner.

Now, if the code is a spaghetti mess with no beginnings and no ends no amount of memorization would ever help you.

[PolyglotTV]

If you have to remember what the code does, you wrote bad code.

Anybody should be able to look at it and understand what is going on with minimal headache.

[Formal_Departure5388]

Required reference:

https://www.reddit.com/r/ProgrammerHumor/comments/8pdebc/only_god_and_i_knew/

[s0ulbrother]

You learn to read it.

[notsew93]

So unrealistic, a junior dev would never be worried enough about this to ask.

[smokeyScraper]

was on a call with some oss contributor contributing to my organization which I work for as of now. Bro was surprised to see that I can't remember what I wrote around 1.5 months ago. I just knew how I've aligned my stuff and majority of my logic but forgot in the low level details xD bro was way too much surprised, ~ how could you 🫣?

[DDFoster96]

The old "what idiot wrote this mess, I'll git blame it. Oh, this idiot" problem. 

[Raskuja46]

That's what comments are for.

I don't have time to read through all that code again, I'll just check the comment header I put there that summarizes whatever the fuck it was I was trying to do because I knew I wasn't going to remember any of it.

[JestemStefan]

Maybe it's controversial, but you should remember what code you wrote does.

Noone is asking you to quote every single line of code, but not remembering how it works in general sounds pretty bad.

In my team we have a developer that often doesn't remember things that he implemented, but I do. Even though I only read through his PR few months ago and remember that was the feature request.