I’m Bill I don’t comment my code (except complex parts), instead I try to make code clear, including using proper variable and function names and try to keep functions short. I don’t think I ever got lost in my own code in my 20+ years of experience. Even got complements about it.
The programming language is meant for humans to read/write, if you need to put comments to understand your code then your code sucks.
When writing basic business code, structuring the code well and having good naming standards means you shouldn't need a ton of comments, but you should still have some. Plus, using structured function content blocks gives you intellisense in some languages and IDEs, which is important for code reuse in teams.
However, when I was doing scientific programming I'd have comments for almost every line at times where I put the mathematical formula and operations the line represents. Implementing a convolution neutral network with parameters to dynamically scale the layers or MPI stochastic simulations is much different than writing CRUD functions or basic business logic.
I’ve seen this same thing happen with Python’s type hints. Turns out giving an “escape hatch” type for devs who have no clue what the type actually is leads to a lot of useless type hints.
Yeah, it’s especially bad, when a library doesn’t provide type hints itself. It can be comically difficult to find out what the return type of a function is, because every if-else-branch might have a different return value, so you may need to read the function body in full to figure out what the type might be.
Add to that, that lots of the tooling around type hints isn’t as fleshed out / useful as it is in fully typed languages and I can definitely understand why someone might not immediately feel like it’s a valuable use of their time.
JSON for serialization all the way. It’s simple and to the point. It does one thing and does it well. There’s little room for annoying surprises. Any JSON can easily be minified and prettified back and forth. If you want it in binary format you can convert it to BSON.
Yaml is too much of a feature creep. It tries to do way too many things at the same time. There are so many traps to fall into if you’re not cautious enough. The same thing can be written in multitudes of ways.
I mean, there’s a difference between something being phrased in an odd or confusing way, and a pedantic comment about whether you should use a Latin plural. 90% of the time you get the latter.
90+% of the time you get common mistakes. Should ofs, they’re - there - their confusions, apostrophes for plurals.
The kind of thing that confuses ESL speakers. The decent thing would seem to be to try and stick to the way it’s taught rather than go with the “it doesn’t matter” route when it absolutely matters to some.
If you’re speaking to someone ESL, don’t do not even use contractions. They are perfectly valid but they are confusing to those new to the language. I also like to put all idioms in quotes when writing, as those are confusing in any new language. Misspellings are less of an issue than you might think because English spellings are dumb and arbitrary already.
When someone tells me “um, it is cacti, AKCTUALLY” I do not think concern for an ESL person listening in is the main motivation, though.
I think you and I have very different experiences. I rarely see that kind of correction if ever.
When you’re in a public space you never know when your words are being consumed by an ESL speaker. I think the best approach is natural yet accurate. They’re going to encounter contractions when dealing with native speakers, but the difference between it’s and its, for example, can be tricky so try to use them as taught.
Spelling mistakes can absolutely be an issue. It’s already hard enough to figure out English spelling without native speakers making it worse. Add on to that the difficulty in any added language of working out near homophones, let alone actual homophones.
I knew someone who was pretty decent with English as their third language but had trouble keeping Texas and taxes straight. I know another guy who is American and uses no in place of know. That one threw me for a while before I figured out what he was trying to say.
I will admit, I do like that “technically” the plural for octopus is “supposed to be” octopods (pronounced like oc-tip-o-dees) but that’s a fun “fact”, not a correction I’ve ever tried to make.
I didn’t want to come off dismissive asking how often you’re talking about those specific kinds of plants but maybe it’s a relevant question after all lol
Depends on how you talk and what you define as normal. How much C++ is still using C++98 and how much uses C++20? It’s pretty silly of a comparison. As someone else put it, corrections are also there for a third party.
But let’s get down to the issue. You are right, correction of English is used as an insult a lot of the time. Sometimes correction of code is also used as an insult. When correcting someone is used out of line and abused, it’s always a bad thing. Correcting someone should never be used to insult.
If you don’t mind, let’s go down a rabbit hole, if you don’t care to join feel free to stop reading here. The upshot is that you are correct because the intent behind correcting English is usually abusive.
So, I corrected you earlier but this is to create a conversation. This is something I’ve been noticing a lot in social media overall: corrections seem to create conversation where if you agree with someone it’s not typically a conversation. “Yeah, you are right…” isn’t a path to an interesting exchange of ideas. There is another way that I’d also love to encourage people to try. Asking questions and digging into why. I’ve seen this happen a few times and it feels like it’s taken more as an insult. A lot of people get defensive if you ask “Why is this something you think.” We’ve created an internet culture of correction, where correction makes conversation. I wonder if this stems from people on the internet correcting people as an insult. Anyways, thank you for reading this random tangent :D
But let’s get down to the issue. You are right, correction of English is used as an insult a lot of the time. Sometimes correction of code is also used as an insult. When correcting someone is used out of line and abused, it’s always a bad thing. Correcting someone should never be used to insult.
I like this. I don’t think that’s the intention for a lot of pedants, but rather they hold a belief in prescripitivism, and have taken it upon themselves to enforce the rules as they imagine them, for one reason or another. That being said, it’s still telling someone they’re wrong without any possibility of improving present or future discussions, and that’s why it’s annoying.
So, I corrected you earlier but this is to create a conversation. This is something I’ve been noticing a lot in social media overall: corrections seem to create conversation where if you agree with someone it’s not typically a conversation. “Yeah, you are right…” isn’t a path to an interesting exchange of ideas.
It’s true, and I think there’s some people that like that approach more than others. I wonder if that contributes to the high number of lurkers on every platform. The main other kind of space centers around venting about a common complaint as the main form of discourse, and those always end up being a little unhinged after a while.
Asking questions and digging into why. I’ve seen this happen a few times and it feels like it’s taken more as an insult. A lot of people get defensive if you ask “Why is this something you think.” We’ve created an internet culture of correction, where correction makes conversation. I wonder if this stems from people on the internet correcting people as an insult.
You know, I’ve never thought about it that way, but you’re right. Every once an a while I see someone take a truly odd position on something, and I end up just asking questions because it’s new and interesting and I don’t really have a bottled comeback. It seems like that actually makes them more defensive than if I had just called them an asshole.
Anyways, thank you for reading this random tangent :D
You’re welcome, it was a good one!
Edit: Oh yeah, and on C, I was expecting someone to mention it. It’s an outlier in being way more static than pretty much every other programming language, but it’s still faster changing than the average natural language. Maybe casual Hebrew has changed more since the 60’s, I guess.
What if your grammar is that bad that people struggle to understand you?
I know someone who is incomprehensible most of the time. I have to ask probing questions just to vaguely understand what they’re trying to communicate. I’ve politely told them more than once about the issue but they never try; they’re not mentally challenged or anything, just an ass.
me when first starting out at a job commenting everything I can
VS
me a couple years in completely lost because I never updated the comments and now none of them make any sense whatsoever
Commenting well is a highly advanced skill. I generally prefer no comments on code since it’s less likely to confuse people and I’ll merrily purge auto-doc comments and anything like
I write a lot of fairly simple scripts in Bash and PowerShell that should be easily understood by anybody else with moderate experience in the language, but I leave a lot of obvious comments because my coworkers don’t write any code and are extremely skittish about my automations. I add them basically to quell their fears.
These are scripts that manage stuff on a few hundred user endpoints and a few servers. They were doing basically everything manually until I got here, and the only way I could get them on board with my slow introduction of automation is to let them see it. I have to ensure things don’t get too long, complex, or hard to explain, or they start getting nervous.
Yeah. Most of the time I use comments in my algorithms, as they often use some weird optimized black magic which are difficult to understand without comments.
There are some cases though where the code is just complicated for reasons outside of your control, in which case “what” comments are good - but they should never be taken at face value, but only used as a first step in understanding the code. There’s a significant risk of the code not actually doing what the comment says.
In my experience refactoring lots and lots of crappy code left by devs long gone, a dev who can write useful comments is by and large a dev who can write code clean and simple enough not to need them. If the code doesn’t have informative names and clear separation of concern, chances are a comment won’t help because the dev didn’t really know what they did that worked in the first place.
Generally, yes. However I have been known to document exactly why I’m doing something incredibly stupid - because it’s required but a stupid third party library which, despite being awful, is still better than implementing it myself as a refactor.
I’d rather teach people to comment well through my reviews. Much easier to understand two lines of well written function description in English than 20 lines of code.
This is terrible! What half-witted shit-for-brains monkey crapped this craptacular crapfest out?! I swear to Kaballah Monster, as soon as I figure out…
I believe that type of stuff is specified in your locale, so it’s possible that it would do the right thing if you’ve set your language to Turkish. Please try it and let us know though :)
The reason is in fact not only because of this exact symbol, but because people tried to change program’s behavior in a malicious way by replacing legitimate code with same looking symbols.
programmer_humor
Top
This magazine is from a federated server and may be incomplete. Browse more on the original instance.