I’ll take variables like “nextTaskToDisplay” over “t” any day, especially paired with good comments explaining non-obvious behavior and doc comments with examples as-needed
As an engineering intern, I was once handed a huge load of Intel 8080 assembly language that had zero comments but used women's names for all labels, variables, etc. There were all sorts of statements like SYLVIA: JMP JUDY. It was impenetrable.
It’s so much easier to read some certain math equations when you can just use short 1-2 letter variables. In the relevant context, I feel x, x2, y, y2, etc can be fine.
My rule of thumb has always been to name members, functions, and variables as descriptive as possible (while avoiding verbosity). Then, I only need to comment on the behavior of individual blocks of code or algorithms since the general intent should be clear in the naming.
No. Code changes leave comments and variables detached from reality. Code is the reality. Unit tests are bound to reality. Focus on code first, then unit tests as stories about code, and then variable names and the comments.
only time I use comments is when something actually needs to be clarified (and those comments will often end up as whole paragraphs). if you use tons of comments throughout explaining every little thing, you are either _massively_ over-commenting or your code is not good.
A big part of that blame falls on entry level programming courses taken by engineering majors. When I took my first one, I was told to comment *everything*.
Not when you’ve been asked to debug 111 pages of variables called z, zz, zzz, zzzz, zzzzz, zzzzzz, zzzzzzz, zzzzzzzz… (true. And to save time,I rewrote the whole thing from scratch.)
Whenever a data scientist hands me some sort of script or jupyter notebook full of one letter variable names that tell me nothing I feel like I'm about to become violent.
There's a whole generation of coders out there who learned the best path to job security was to make code so arcane, obtuse, and inscrutable that only they could have any hope of maintaining it.
I've seen multiple critical apps done in this style, and the grinning wizened goblins who wrote 'em.
I don't even use one letter variables in my repl when I'm just checking things out. I use two, duplicate letters or more. Usually starting with qq because crying usually begins at that point.
LOL I started coding in 1970 and spent a substantial part of my time writing in assembly language (“what’s that?” the web developers chant in unison 😆)
I try to do both. If I have an option for a data field name, like from XML or SQL, I will use that in preference to an index number. Just trying to make it readable for future me/future programmer.
I swear I woke up one day and suddenly my commits were dinged because of comments in the code. I have never run down who made that decision and why, but I don't like it.
💯 variable names, well named functions, speak volumes. Drives me nuts when I see people name things (without any kind of Type information nearby) `data`, like, come on now, that is useless.
2. Stop overloading stuff. Variables are names for the placeholders that hold the values. Let them be.
3. If code is complex, there is no harm in leaving comments to address that.
I’ve definitely had instances where this has happened to me as well. I usually try to mitigate it by emphasizing modularization to slim down file lengths. Then, I add a comment block to the top of the file containing a legend describing each identifier’s meaning and usage
I think some people do it to show the arguments but most IDEs will do that if you hover over the function name.
In this case, it also stops forEach() passing unintended extra arguments to the function (the index and the array), which might be important if the function takes optional args.
Back in the 8-bit days we often couldn’t use more than one letter for variable names. Heck, we often ran out of ‘1’s and ‘0’s and had to use ‘I’ or ‘O’! 😉
I used to name temp variables by their type and scope g_int, g_date. g_string was always my favourite.
Think that's lame? In the massive Oxford Greek-English lexicon, there is one joke. Bousphorus (Bous=Ox, phorus=ford) - is translated as Oxford - with the 'O' capitalized.
“if you have to explain it with a comment you probably misnamed it”
If it’s a complex bit of maths (I ‘do science’, so sometimes it is) I’ll put a reference to the source of the maths (maybe a paper, or a reference to a tutorial).
Variable names describe what they store
Method names describe what they do
Class names describe what they're for
Interface names describe a feature set
The code itself should obviously describe current behaviour
So add a comment to explain why the code does something that seems wrong(silently ignoring an error because we recheck for success later anyway, or using a constant with the wrong name because the library has a bug), or cannot be otherwise made clear(say expecting event listeners or DB triggers).
Duel has been initiated. Challenged player please reply either "Accept" or "Reject" after approximately 10 seconds. Duel Initiator may also reply "Reject" to cancel.
It all has its place. Good naming removes a lot of the need for comments, but they can be useful when a routine does something novel, or clever, or in reaction to a limitation in the system.
It’s just an aspect of clean code called “self-documenting code”. Comments are still great for elaboration/context but proper clean code should be written in a way that the next engineer can understand what is happening *without* all of the context.
Which is great, until you get far enough into abstraction and you get partialShortContainerForDocumentFenerationFactoryWorker, and all of the sudden docFact starts looking pretty nice...
I've found that it IS quite helpful, though. For one thing, establishing what it *does* do is a step towards making it do what it's *supposed* to do. For another, I find that quite often, the "self-documentation" describes what it's supposed to do rather than what it does do
Not sure I understand how "self-documenting" code can describe what it was intended to do if it's implemented incorrectly. If the code increments a counter, how does that tell you the programmer meant to decrement it?
Most real-world examples that come to mind are more complicated than that and their context would be NDA'd. That being said, I once saw a case where a variable was called something like "heightAboveFloor" and the calculation that populated it had a math error that could put it UNDER the floor...
And speculating somewhat, I could easily see a case where the counter is actually named something like "attemptsRemaining" and you see "attemptsRemaining++" at the end of a block that's clearly processing whatever an "attempt" is (and the ++ came from copy/paste).
I was told early in my career, "structure your code and name your variables and functions as if the next person working on it was an axe murderer with your home address". After 20+ years, no one with an axe has come looking for me.
I get your point but var names that are used a lot and overlong make code hard to read, IMO. I try very hard to make my method names like documentation but vars not so much. ¯\_(ツ)_/¯
This is a big part of why I like strongly typed languages. You get the purpose from the name, sure, but with type information you also know /exactly/ what it is
My rather 'unusual' handle is code for I actually got through to the end the late David Foster Wallace's masterpiece novel 'Infinite Jest.' Haha, and I used to comment on Disqus under the handle 'aardunza'. That is all -- nothing nefarious.
These days variables can be as long as you like, I still remember having to keep them to 8 characters. All in caps. And code comments? Waste of storage space, just write them in the manual and ship it
Changing types requires changing names, prefixes clutter the code pretty fast and Modern IDEs and text editors have static typing making Hungarian notation redundant, inefficient and high maintenance.
I usually work with a text editor and a compiler, but don't tell me to do it without syntax highlight and static typing. I know it's possible but it prefer not to specially when tree sitters and LSP are available and easy to integrate into text editors.
Comments
We got tracing going & realized it in fact was anonymous functions all the way down. So much damned hate!
ArrayList al1();
I've seen code like this, and it's a nightmare to maintain.
Single letter variable names are a mistakes in most cases (except as indices).
It’s so much easier to read some certain math equations when you can just use short 1-2 letter variables. In the relevant context, I feel x, x2, y, y2, etc can be fine.
But mostly yes, use descriptive names.
thisPost = true
👏()
Comment out code, receive coded code.
It's a joke.
Yes, I do believe you're right.
_ = DoSomething();
Wait....yup, it does apply 🤓
I've seen multiple critical apps done in this style, and the grinning wizened goblins who wrote 'em.
IHateMyLife = true;
}
Well, in a decent language, anyway.
*That escalated quickly
free(nelson_mandela);
ORG ASM and
BRA CUP
The mnemonic for Sign Extend was often SEX which could be mis-used with various labels too.
cursOfTheWerewolf
cursOfDracula
Y’all never wrote a lick of VHDL or Verilog. Coding for hardware (integrated circuits) will put weakling software devs to bed real early. Night night!
const thisIsStupid = "-1";
// XXX magic number
What, exactly, do YOU think "pickstockfororder" does, Greg?
2. Stop overloading stuff. Variables are names for the placeholders that hold the values. Let them be.
3. If code is complex, there is no harm in leaving comments to address that.
Mine are just outdated memes
Descriptive Variables is probably one of the best practices I've picked up in all my years of coding.
presents.forEach(p => deliver(p))
is fine. Sometimes short is more readable.
`presents.forEach(deliver)`
Is no variable better than a short variable? 😅
In this case, it also stops forEach() passing unintended extra arguments to the function (the index and the array), which might be important if the function takes optional args.
😔
Very clear and understandable difference
Fun fact, Spanish is no longer on my resume.
Think that's lame? In the massive Oxford Greek-English lexicon, there is one joke. Bousphorus (Bous=Ox, phorus=ford) - is translated as Oxford - with the 'O' capitalized.
if you have to explain it with a comment you probably misnamed it
If it’s a complex bit of maths (I ‘do science’, so sometimes it is) I’ll put a reference to the source of the maths (maybe a paper, or a reference to a tutorial).
Variable names describe what they store
Method names describe what they do
Class names describe what they're for
Interface names describe a feature set
The code itself should obviously describe current behaviour
Comments should be for everything else.
I started by refactoring the creature.
As a programmer, I agree. But, still, we fight.
what the code should do (and how) should be documented at top of file.
self-documenting code *reduces* the amount of non-code documentation you need to write.
no idea why that isn't canon.
https://github.com/timmerov/technomancy/blob/master/pickleball/src/main.cc
🙃
I'd say variable names are mnemonics, and when chosen well they can be intention-revealing.
But that's not the same as code comments.