every programmer I’ve seen who says their code is self documenting writes dogshit code
I think we’re all just dogshit but think we’re better than the next person, it’s like driving. I’m a “comment if there’s no way to make it readable” kinda guy, I work with some “comment and don’t bother to make it readable because there’s comments” people. We all suck. I probably forget to comment on unreadable places sometimes, or overestimate readability he either doesn’t update comments so they’re out of date or the code is so gibberish that a comment didn’t help.
Ideally I guess you comment AND make it readable AND make sure the comments are up to date, but who do you think we are? Superman? And what’s the right level of commenting anyway? Probably depends on who is reading them.
The link is a proxied image link for some reason.
- N-deep loops mixed with gotos, throws, multiple returns, and mixed memory management contracts.
#include “globals.h”
// please help
With the short variable you probably also get shadowing. That’s super fun in a new code base.
Or another favourite of mine: The first time I had to edit a perl script at work someone had used a scalar and a hash with the same name. Took me a while to realize that scalars, arrays, and hashes have separate namespaces, and the two things with seemingly the same name were unrelated.
Ngl that’s like baby levels of nasty code. The real nasty shit is the stuff with pointless abstractions and call chains that make you question your sanity. Stuff that looks like it’s only purpose was to burn the clock and show off a niche language feature. Or worse than that even is when the project you inherit has decade old dependencies that have all been forked and patched by the old team
If all I had to worry about was organization and naming I’d be over the moon
Git commits with message saying “pushing changes” and there are over 50 files with unrelated code in it.
“fixed issue”
“Fix for critical issue.”
Followed by an equally large set of files in a commit with just the message:
“Fixup”
And then the actual fix turns out to be mixed in with “Start sprint 57 - AutoConfiguration Refactor” which follows “Fixup”
“stuff, lol”
Stuff1, stuff2 …
In the past I had commit messages with change numbers from a system, that was no longer in use.
So the commit just said “CH-12345“. It is the kind of annoying, where you can’t even really be mad at someone.
I put my ticket numbers in my tickets, but i also try to describe the change too (e.g. “Fix bug where xyz happens due to zyx action”). Also, atomic commits: commit only related changes.
Yes, it takes longer to commit large changes, BUT you can easily merge the commits, and rollback only what needs to be rolled back.
Former coworkers: “oh, these two lines are the same in function x and function y. TIME TO ABSTRACT”
Such DRY
The real nasty stuff is not code it’s in proprietary blobs which can only be edited through proprietary software. The documentation is shit (because the editor also sells training) and there are no communities (because implementation specialists think having secrets is having an edge).
My favorite was an abstract class that called 3 levels in to other classes that then called another implementation of said abstract class.
And people wonder why no one on our team ever got shit done.
And hard casting onto the wrong class because a neat function lives in there (who will detect you did that and treat you a little different because you don’t have all the resuired data in that class instance) as a “quick fix”
Even if the abstractions aren’t pointless, there’s a limit to how many levels of abstraction you can make sense of.
I’ve seen some projects that are very well engineered, with nice code, good comments, well named variables and functions. But, the levels of abstraction and nesting get so deep that you forget why you were digging by the time you get somewhere relevant.
What’s frustrating there is that you can’t blame someone else. It’s just a limit for how much your brain can contain.
Even worse than there being no comments: the code is extensively commented, but its function has drifted from what the comments describe to the point where they are actively misleading.
The good old “signal left when switching to right lane.”
I mean sometimes you gotta trick the compiler to get a leg up in runtime.
longest file I have ever maintained contained 50,000 lines of code.
fifty THOUSAND.
forgive me for not weeping for 2000 lines.
my advice, don’t fucking touch it. pull out as much functionality out of it into other things over time.
there will come a day when you can throw it away. maybe not today, maybe not tomorrow… but some day.
Yeah, been there. The codebase I worked on also had a single method with 10k lines.
The database IDs were strings including the hostname of the machine that wrote to the DB. Since it was a centralized server, all IDs had the same hostname. The ID also included date and time accurate to the millisecond, and the table name itself.
Me: Mom, can we have UUIDs? Mom: We have UUIDs at home UUIDs at home: that shit
You should add the local weather forecast, a random fun fact and the canteen menu of the day to the key to make it more interesting to read.
I was working on a project that had 100 000 line oracle database PL/SQL procedure that ordered a work order from subcontractor. It was just one single function. That was called by classic asp + visual basic COM component.
Oh Lord, I get Vietnam flashbacks about it.
Jesus i worked at exactly this kind of project once. The only other dev was also very hostile and protective of this position. He did not want me there in the slightest. Took about 6 months before we cancelled the contract since this dude was just actively harrassing me in Teams DMs on the daily and he just ignored all my concerns regarding maintainability since “he could understand the code” and i was probably just “not experienced enough”.
Don’t downplay what this does to your mental health. 5 years of workplaces like this and I’m now starting to see a therapist due to exhaustion disorder symptoms in my goddamn 20s. Take care our there!
So infuriating when you have some dickhead making themselves unfireable by intentionally convoluting the codebase and chasing out any other hire. And even worse when management bought into it and think the guy’s an actual irreplaceable genius.
Probably even believes it himself. I hate narcissists.
I literally told my boss that I was just going to rebuild the entire pipeline from the ground up when I took over the codebase. The legacy code is a massive pile of patchwork spaghetti that takes days just to track down where things are happening because someone, in their infinite wisdom, decided to just pass a dictionary around and add/remove shit from it so there is no actual way to find where or when anything is done.
FUCK. Triggers me. Just got let go from a place that had this problem and wouldn’t let me make any changes whatsoever. I didn’t even push hard.
I did this once
I was generating a large fake dataset that had to make sense in certain ways. I created a neat thing in C# where you could index a hashmap by the type of model it stored, and it would give you the collection storing that data.
This made obtaining resources for generation trivial
However, it made figuring out the order i needed to generate things an effing nightmare
Of note, a lot of these resource “Pools” depended on other resource Pools, and often times, adding a new Pool dependency to a generator meant more time fiddling with the Pool standup code
Side-rant:
I rarely write Python code. One reason for that is the lack of type safety.
Whenever I’m automating something and try to use some 3rd party Python library, it feels like there’s a good 50/50 chance that front and center in its API is some method that takes a dict of strings. What the fuck. I feel like there’s perhaps also something of a cultural difference between users of scripting languages and those of backend languages.What you described sounds so much worse though holy shit.
Yeah, the new pipeline is based HEAVILY on object inheritance and method/property calls so there is a paper trail for ALL of it. Also using Abstract Base Classes so future developers are forced to adhere to the architecture. It has to be in Python, but I am also trying to use the type hinting as much as humanly possible to force things into something resembling a typed codebase.
I was part of project that scoffed at the idea documenting code. Comments were also few and far between. In retrospective, it really seemed like they wanted to give that elitist feel because everything reeked of wanting to keep things under wraps despite everything being done out in the freakin’ open.
The language is COBOL.
your paycheck is $5000 because you know COBOL
What? I make that kind of money by dabbling in Ansible, Python and Kubernetes. $5000 sounds pretty lowball for fairly niche knowledge like COBOL.
*sigh* why the fuck didn’t I major in CS!?
I don’t know, but for me it was undiagnosed ADHD. 😋 Fortunately IT is one of the areas where lack of a degree isn’t a showstopper.
i mean i recently did a contract gig updating a 6 year old legacy codebase in a language I’ve never used
oh also I’ve barely coded anything in my life
you guessed it, i used an LLM (as the contracter requested, but still…) ¯\_(ツ)_/¯
so i keep waffling between “my (then) undiagnosed ADHD would have stunted my CS learning hard enough that I’d barely be any more knowledgeable than I am now anyway” and “despite it being a terrible fucking idea companies are going to try their damnedest to replace all software engineering with vibe coding”
so i end up back at “at least i have a degree in pipetting and can go get a $20/hr job moving small volumes of liquid back and forth until pipetting robots become cheaper than me”
Pretty sure that knowing COBOL isn’t the hard part. It has relatively few language concepts.
This lack of language concepts just makes it difficult to reason about it, so that’s what you’re getting a paycheck for. Well, and possibly also because it might take months to have a new dev figure out your legacy codebase, so it’s cheaper to keep the current dev by paying them competitive prices.
Per day.
Not quite. More like per 40 hour week with no overtime, but my father insists on having up to 20 hours a week of overtime he’s allowed to burn, so it’s kinda like $7,500 a week. He generally gets paid byweekly or monthly. Subcontractor and all that BS
subcontractor
that’s why it’s $7500.
COBOL. That’s why he’s a subcontractor. Not like they taught COBOL in my CS courses in university in 1998-2002.
Hey! This was my first real job. Is Matlab code written by physicists who just recently learned programming.
My first thought immediately was of academia also.
I just inherited my first codebase a few months ago. It’s like this everywhere and original developer was fired, so what should sometimes be a simple fix turns into a full day of finding what needs to change. Any recommendations on fixing/maintaining code like this or should I just make it the next person’s problem?
-
if it’s not in git / SVC, add it as is. Create a “refactor” branch, and liberally use commits
-
Treat it like a decompilation
Figure out what something does, and rename it (with a stupidly verbose name, if you have to). Use the IDE refactor tools to rename all instances of that identifier
-
Take a function, figure out what it does, and refactor it in a way that makes sense to you
-
Use the editor’s diff mode to compare duplicate code, extract out anything different into a variable or callback, and combine the code into a function call. Vscode’s “select for compare” and “compare with selected” are useful for this
-
Track what you’re doing / keep notes in something like Obsidian. You can use
[[Wikilinks]]syntax to link between notes, which lets you build a graph structure using your notes as nodes -
be cognizant of “Side Effects”
For example, a function or property, or class might be invoked using Reflection, via a string literal (or even worse, a constructed string). And renaming it can cause a reflective invocation somewhere else random to fail
Or function or operator overloading/overiding doing something bizarre
Or two tightly coupled objects that mutate each other, and expect certain unstated invariants to be held (like,
foo()can only be called once, orthingyA.len()must equalthingyB.len()- write tests if you can, either using a testing framework or custom Python scripts
You can use these to more thoroughly compare behavior between the original and a refactor
- if something feels too “heavy”, like it’s doing xml formatting, file manips, a db insert, and making coffee, all in a single class or function
Separate out those “concerns”, into their own object/interface, and pass them into the class / function at invocation (Dependency Injection)
- use “if guards” and early returns to bail from a function, instead of wrapping the func body with an if
public Value? Func(String arg) { if (arg.IsEmpty()) { return null; } if (this.Bar == null) { return null; } // ... return new Value(); /// instead of if (!arg.IsEmpty) { if (this.Bar != null) { // ... return new Value(); } } return null; }Lowering indent levels is nice in functions. Early returns mean you don’t have to think as much. “If it got here, I know foo isn’t null because it already would have returned”.
I always feel bad about putting little ifs at the top of functions. Is it not bad practice? I like them because they’re simple to implement modify and read, but I have this voice telling me I need to make things more impressive.
Never make things more “impressive”
Make them more comprehensible
Reduce the cognitive load required to understand and reason about a piece of code. Honestly, the more you can express complicated ideas simply, the more impressive you are
I started putting a helpful comment above the ifs as a seperator to cope with that.
public Value? Func(String arg) { // Sanitize. if (arg.IsEmpty()) return null; if (this.Bar == null) return null; // Get [that] and/or do [this]. var foo = this.baz.foo; ... return new Value(); }
I use sentences as variable names sometimes, because I necessarily end up with lots of similar-sounding variables or functions.
List_of_foo_dicts = Get_foo_from_bar_api()
-
Add comments as you go
You’re going to want to follow the “campsite rule” everywhere you go, and also sneak in positive refactors into your feature changes (if business is not willing to commit time to improving the maintainability of the codebase).
Read up on good software design principles. I don’t know you experience level, but for instance, everyone agrees that appropriate abstraction, and encapsulation make code easier and more enjoyable to work with, and will let you run tests on isolated sections of the code without having to do a full end-to-end testsuite run.
Having tests that you trust, especially if they execute quickly, will increase your “developer velocity” and let you to code fearlessly–knowing that your changes are reasonably safe to deploy. (Bugs and escaped defects will happen, but you just fix them and continue on.)
Good luck!
ARGH this triggered a bit of PTSD for me…
“We’re going to convert these COBOL applications to C#, and you need to test that the new application works exactly the same, including the same bugs as the old application.”
“Ok, where’s the specifications and test reports of the old COBOL applications?”
“They were lost to time, we don’t know where they are.”
“Ok, so how are the developers going to write the C# code?”
“They’re going to read the COBOL scripts and recreate them into C#, we advise you do the same.”Cue me spending a month trying to decypher the COBOL gobbledigook into inputs and outputs, and write testcases based on that. And after that month was up, and I had delivered my testcases, they told me that my services were no longer needed.
I had delivered my testcases, they told me that my services were no longer needed.
Gee, I wonder how all those specifications and test reports became “lost to time”…
deleted by creator
Something that I’m disproportionately proud of is that my contributions to open source software are a few minor documentation improvements. One of those times, the docs were wrong and it took me ages to figure out how to do the thing I was trying to do. After I solved it, I was annoyed at the documentation being wrong, and fixed it before submitting a pull request.
I’ve not yet made any code contributions to open source, but there have been a few people on Lemmy who helped me to realise I shouldn’t diminish my contribution because good documentation is essential, but often neglected.
The fact that documentation and comments can’t “fail” if the underlying code changes is a real problem. I’ve even worked at places which dictated that comments had to go directly above or even beside (inline) with the code they were explaining, so they would show up in any patches changing the code.
What do you think happened? Yup, people would change code and leave the outdated (and wrong) comment untouched, directly to the right of the code they just changed.
Hell, I was one of those people, so I get how it can happen.
Code was written before git was invented.
deleted by creator
https://en.wikipedia.org/wiki/Git
Initial release 7 April 2005; 20 years ago
Oh ohThere was sccs (1973) and cvs (1986) before git.
Yeah but you merged as you wanted, usually anyway.
Oh merging was a total crap shoot with sccs. It was better with cvs, until it wasn’t and then it was very very bad.
