I’ve worked in a few startups, and it always annoys me when people say they don’t have time to do it right. You don’t have time not to do it right - code structure and clarity is needed even as a solo dev, as you say, for future you. Barfing out code on the basis of “it works, so ship it” you’ll be tied up in your own spaghetti in a few months. Hence the traditional clean-sheet rewrite that comes along after 18-24 months that really brings progress to its knees.
Ironically I just left the startup world for a larger more established company and the code is some of the worst I’ve seen in a decade. e.g. core interface definitions without even have a sentence explaining the purpose of required functions. Think “you’re required to provide a function called “performControl()”, but to work out its responsibilities you’re going to have to reverse-engineer the codebase”. Worst of all this unprofessional crap is part of that ground-up 2nd attempt rewrite.
Ironically I just left the startup world for a larger more established company and the code is some of the worst I’ve seen in a decade. e.g. core interface definitions without even have a sentence explaining the purpose of required functions. Think “you’re required to provide a function called “performControl()”, but to work out its responsibilities you’re going to have to reverse-engineer the codebase”. Worst of all this unprofessional crap is part of that ground-up 2nd attempt rewrite.
I think this is actually quite common in commercial code. At least, for most of the code I've seen. Which is why I laugh most of the time when people imply commercial code is better than most open source code. It's not, you just cannot see it.
Writing good comments is an art form, and beginner programmers often struggle with it. They know comments mostly from their text books, where the comments explain what is happening to someone who doesn’t yet know programming, and nobody has told them yet that that is not at all a useful commenting style outside of education. So that’s how they use them. It usually ends up making the code harder to read, not easier.
Later on, programmers will need to learn a few rules about comments, like:
Assume that whoever reads your code knows the programming language, the platform and the problem domain at least in general terms. You are not writing a teaching aid, you are writing presumably useful software.
Don’t comment the obvious. (Aside from documentation comments for function/method/class signatures)
Don’t comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments. Reserve the “what” style comments for where that just isn’t possible.
Do comment the why. Tell the reader about your intentions and about big-picture issues. If an if-statement is hard to parse, write a corresponding if clause in plain English on top of it.
In some cases, comment the “why not”, to keep maintenance programmers from falling in the same trap you already found.
Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that’s obvious to one person maybe isn’t so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
Comments aren’t the actual documentation and aren’t a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren’t programmers themselves. They can’t read the code or don’t have access to the code. Writing documentation is still important.
Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I’ve worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I’d rather have no comments than wrong comments.
This is a notoriously bad book. If you read the part about comments (which I don’t know about, and am willing to accept is good) make sure to skip everything else because Robert Martin is a fraud.
I would argue that if an if statement is hard to parse, replace the entire condition with simpler to read (but way more specific) variables that you assign values (the original condition expression) in the line above. No need for comments in that case
In this day and age of source control I don’t think this is fully necessary. If you want to know the why, you can look into the commit history and see which ticket is connected to it. There you might even see the discussions around the ticket as well. But this requires good source control discipline.
Why not put the “why” in a comment and save people the job of dredging through old commits and tickets to figure out what the code is for? I’d thank someone for saving me the hassle.
Going back to the original ticket can offer far more info than what any “why” comment can give. You can see how old it is, if there are any connected tickets, who were involved with it, step by step instructions how to reproduce the bug, etc.
In any modern IDE “dredging through old commits” means clicking a single button to see who last changed the line. From there it often makes sense to go look at the PR to see a higher level of what was changed. You cannot include all of that context in a single comment.
Don’t comment what a line is doing. Instead, write your code, especially names for variables, constants, classes, functions, methods and so on, so that they produce talking code that needs no comments.
Over and over and over again in my experience this just doesn’t work. Readable code does not substitute for comments about what the code should be doing.
It’s not that bad. It definitely helps in long functions.
I’m an advocate for code commenting itself, but sometimes it’s just better to comment on what you’re doing, and in those cases it helps to over commentate.
Instead of letting the reader interweave code reading and comment reading, I think it’s better to do either. Either you go full self describing code, letting the reader parse it as code,m, or you abstract everything, making it more of an explanation of your reasoning, and abstract lines that may look too complicated.
Not every comment needs to be useful, but I still write them to not have this switch between reasoning and thinking in code. It can also double as rubber duck debugging too!
Just remember we got rid of TLS 1.0 the same thing can be done with IPv4. It’s time for browser makers to put “deprecated technology” warnings on ipv4 sites.
IPv4 isn’t depreciated, it’s exhausted. It’s still a key cornerstone of our current internet today.
We still have “modern” hardware being deployed with piss-poor IPv6 support (if any at all). Until that gets fixed, adoption rates will continue to be low. Adding warnings will only result in annoying people, not driving for improvement.
exhaustion probably also constitutes as “deprecated” once the utility of a system designed to be, well, useful no longer meets the usefulness quotient that it previously provided. Suddenly It’s “deprecated technology”
genuine question, any reason not to just actually deprecate it then? Like just stop producing hardware that routes IPV4. Chances are there’s enough that’ll already do IPV4 it won’t be a problem, and im sure if you really needed to, you could figure something out.
Reminds me of every fuckin PR I do for the Indian contractors that were sold to us as “senior devs” but write code like a junior and you better believe every other line has the most obvious fucking comment possible
Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.
Better than writing beginner level crap that is at the same time super cryptic and not documenting at all. We have a bunch of that in our codebase and it makes me wonder why these devs are writing extension methods for functionality already built into the standard libraries.
It’s barely supported. Most providers here “offer IPv6”, but each has a different gotcha to actually using it, if it works at all and they didn’t just route you through hardware that doesn’t know what it is.
Mordor itself, Russia. Technically, most ISPs support IPv6 here but as I said each has something weird in config that makes using it… Fun. I don’t remember specifics since I’m mostly looking at it from consumer side, but I could try finding the article (in russian) that talked about it.
My current connection doesn’t have IPv6 at all according to ipv6-test.com, although I’m not 100% if it’s because of provider or Cisco AnyConnect blocking shit.
When you when you sign up for internet here, you get a dynamic IP, it’s been that way for… As long as I can remember, really. Definitely more than ten years. I know in Moscow people used to get white IPs way back when, but that’s long gone. Not really a problem since most people don’t host anything.
It’s becoming more and more of a problem I’d think. Blocklists just become longer, so the more an IP is used by random people the less useful it becomes.
Just because you have a IPv6 address doesn’t mean you’re actually using it. At best you’re tunnelling IPv4 traffic through your carrier’s IPv6 network. Current estimates (from Cloudflare) show only about 34% of the global internet uses IPv6.
If you only used IPv6, you wouldn’t be able to access nearly 66% of the internet.
Not at all only. At times you have both IPv6 and IPv4 and other times you can still get IPv4 at no additional cost like when you run your own router or modem. The layperson will be given IPv6 by default, but it’s not the only thing you can get.
The older ISPs already own all IPv4 blocks, so while they can still give them out to private or professional customers, it would be stupid to sell the blocks to competitors.
More useful would be what sort of values is acceptable there. Can I use team number 2318008? Can I use team 0? If not, why not? WHY / WHY NOT is often useful.
LLMs aren’t virtual dumbasses who are constantly wrong, they are bullshit generators. They are sometimes right, sometimes wrong, but don’t really care either way and will say wrong things just as confidently as right things.
Retardistan is hogging the biggest portion of the IPv4 addresses for themselves. That’s why they have the worst IPv6 support. The need arose last in this part of the world.
programmer_humor
Oldest
This magazine is from a federated server and may be incomplete. Browse more on the original instance.