You must log in or register to comment.
especially your own code.
“This is obvious” I said. “Surely I won’t need to comment this,” I said.
The worst part is when I leave comments and still wonder wtf I was thinking.
My comments are written to be understood by the stupidest person alive, and I am thankful for them.
That comes with experience. I rarely find things I wrote anymore where I could add or remove a comment.
Sometimes one does something in a certain way (which would otherwise be a shit way to do it) for very good reasons which are external to the code, be they requirements related, external upstream or downstream systems or due to existing system limitations or deployment environment.
More than a decade ago, I learned that even if one isn’t at all prone to put comments in the code, you should add comments for such reasons in that quirky code: months or years later that will yield exactly the reaction of this meme when you or somebody else sees that code (whilst you might remember why you did, somebody else will certainly not)
Maybe even more importantly, it allows other people to actually remove that crap if the reasons behind it don’t apply anymore, which they would otherwise not do because they would be fearful that the hacked-together pile of crap was needed for some reason elsewhere they were not aware of so they could not risk refactor it - most long lived codebases out there are riddled with crap which had pretty good reasons to be there back when it was done but it doesn’t anymore, but which newer people can’t just remove until they’ve gained a full understanding of the whole code base and how it’s wired to the rest (and, even then, there’s a risk that the reason is a requirement and if they just remove that code it breaks something that the users expect).
Even if you’re the kind of coder that thinks that “the code is self explanatory” (something which, by the way, betrays a lack of experience in the full life-cycle of software that has been in production for years and been worked on by several people) do your future self and others a favor by explaining the choices derived from external reasons (“Why has the auto engineer chosen to put the steering wheel in a British car on the right side?”) that led to code design which is NOT explainable by purely internal or good design or coding reasons.
(Or at least make it stupidly clear in the appropriate level of tests, which normally is requirements testing or integration testing)
If you’re really good and working in a proper professional environment (most programmer aren’t), consider tracing things back to the entries in the software requirements document, use cases or even elements of an use case, at least for the “quirky” choices.
Definitely. I’ve seen this advice summarized as “Comment ‘why’, not ‘how’” and it’s always helpful to come back to weird code and immediately understand these things.
Yeah, that wall of text is my rationale for doing exactly that.
As the sole programmer of a certain project, I often leave rant comment on what the previous programmer was thinking.
I was complaining to my friends about how bad the programming was on a project I was wrapping up and then they asked, “Isn’t this a personal hobby project?” yes it is.
I like to structure my comments as song parodies and see if anyone notices.
"Is this a real object, or just an interface?
This gets caught in a pipeline, no escape from transformations.
Any way the data goes doesn’t really matter to this service.
…"
Electrical engineer: “what was that other guy thinking?”
Software engineer: “What was I thinking?” (It’s code from last night)
We went out for drinks one night after work. Upon stumbling back to the office, I remembered I had forgotten that I signed up to make a tool page to mange some data ingest. It was due first AM. I was three sheets to the wind. Fired up LAMP stack, took the samples and made an ingest function. Wired up a textbox, tested it and went home.
Next AM, I turned it in, there was a minor bug. No problem, I’ll just find the issue and they’ll be good to go.
cracked the scripts open…
I could read it. I could see what a lot of it did. I could NOT figure out what some of it was there for. I spent 30m trying to figure out what I was doing. it was only a couple hundred lines. It wasn’t even a copy/paste job. Eventually I ran out of time and just leaned into phpdump, and breakpoints to find the exact error. One function hit a bonefied php bug that caused the debug to go silent. large swaths of the code were unreachable due to essentially a couple of typos. The only reason it worked as well as it did was because their sample data was as simple as imaginable. I put on some Nine Inch Nails and just remade it in about 30 minutes (10m before it was absolutely needed)
I’ve learned that my buzzed self has less inhibitions when writing code. But those inhibitions are there for a reason.
What was I thinking?-after every interruption that could have been an email
Electrician: “what was the engineer thinking?”
I watched a team invent a new language to get around updating some eccentric code.
They could have sat down and commented it and made their changes
They could have refactored what was there.
They could have scrapped it and wrote fresh
Instead, they designed an entire natural language system so that non-programmers who were writing in XML could just write in English.
They ended up making so many required keywords as helpers that the non-programmers kept using the old system because the XML was easier for them work with.
Note: wasn’t my code, wasn’t my dept, when I heard the plan I went to check it out, the old system was functional but like C- work at best. At some point, they wrote a compiler for the new system.
I’ll bitch and moan about my own work from a few months ago “before I knew better”.
In each of us, not two, but three. Paraphrasing Superfast matt, “that was done by past baahb, and he’s an idiot, but it matters more to future baahb, and that guy is an asshole.”
I wrote code today I know I will have to touch in 2 weeks. I’m already dreading it. that shits a mess.
i hate when it’s not one person’s fault but like, ten years of bloat. who do i hate for that
Management
Manglement as I call them.
“Which idiot would do that?”
* looks at git blame for the section and promptly shuts up *
Man past me should have done a better job
//Crappy hack to make this work immediately so management will stop breathing down my neck
Oh wait nevermind lol
Should have checked the
blamebefore running clang-format himself.
I don’t think you have to be a software engineer to understand that people do shit half-assed.
Am electrician can confirm
If I dont do it the homeowner tries to and I have to awkwardly nod instead of fixing the problem and that just takes so much longer
Two red flags for trades and swe and other work:
1 - never saying that they would have done it differently if not outright roasting the work 2 - letting someone else take over their project, willingly, and not because they’re busy. Assuming it’s not a pile of shit they don’t want to do.
Fun trick with Markdown. Put a double space at the end of a sentence so it formats the lines correctly.
- Double spaces
- allow for lists.
That’s the part I hate most about being a SWE. Just shut up and do your job. I’ve seen your code. You code like you read blogs for a living.
You code like you read blogs for a living.
Do you not?
No. I code like I know what I’m doing.
*like you think you know what you’re doing. Programming experience is a continuum.
