Reject merge.
Documentation is part of design.
Do it or die in obscurity.
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.
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.
Tell that to Linus.
Shit needs syntax and documentation.
Anything submitted needs to be reviewed before merge/push. Syntax and Documentation rejections don’t result in errors. Get your shit right first. You are trading on someone else’s rep with this.
If you want to push your own code do it with a separate pull. If you want it merged that carries responsibility to the person carrying 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.
- N-deep loops mixed with gotos, throws, multiple returns, and mixed memory management contracts.
#include “globals.h”
// please help
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.
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.
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
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.
Git commits with message saying “pushing changes” and there are over 50 files with unrelated code in it.
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.
“stuff, lol”
Stuff1, stuff2 …
“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”
Former coworkers: “oh, these two lines are the same in function x and function y. TIME TO ABSTRACT”
Such DRY
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”
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).
JavaScript developer in a strongly typed language decoding json into dictionaries with single letter keys.
You got 3 letters?! Luck!
I worked at a japanese company whose engineers we’re former NTT developers. Copypasta (i.e. not using functions), inefficient algos, single-letter var names, remote code execution from code as root, etc. good times!
single-letter var names
in kanji?
Such hits as ‘a’, ‘b’, ‘x’, and ‘y’. I know the version of the language we were using didn’t have native utf-8 support, so I don’t think kanji varnames were possible. It even made comments in kana and kanji really wonky (I think the comments were shiftjis)
f
Those are amateur problems, real problems start when you are unable to run it or you don’t have source code. Bonus, it’s written in the in house language made by developer who left job or died - true story.
Oh God. Story time.
I had an important CICD pipeline that published a dinky little web-thing that was important for customer experience. The first line of the final docker file was
from company-node:base. I had all the source code. I had all the docker files. At no point was there ever a container namedcompany-nodelet alone a tag of base.The one and only version of this container was on the CICD server.
The team lead has spend the last two months writing a permissions library that nobody understands how to use or debug. He wrote it with Cthulhu at his side. Soon not even Cthulhu will understand it.
Well, I’m the only maintainer for my project, so ha! (I only have myself to blame.)
That just means my boss will have to do all the work. Ha, what an idiot. Wait… aw. 🙁
Fork the repo.
Ask an LLM to rename all the variables and add comments and docstrings. Give it your style guide (assuming you have one).
Ask another LLM to check their work.
Done.
Disclaimer: I’m not a programmer, I’m a network engineer who dabbles in automation and scripting. But it seems to me that grunt work like this is what LLMs are really good for.
i and I are acceptable in small loops. But it depends a lot on the language used. If you’re in C or bash maybe it’s fine. But if you’re in a higher level language like C# you usually have built on functions for iterating over something.
For example you have a list of movies you want to get the rating from, instead of doing
for (i = 0; i < movies.length; i++) var movie = movies[i] ....Its often more readable to do
movies.forEach { movie -> var rating = movie.rating .... }Also if you work with tables it can be very helpful to name your iteration variables as row and column.
It’s all about making it readable, understandable, and correct. There’s no point having comments if you forget to update them when you change the code. And you better make sure the AI comments on the 2000 lines of three letter variables is correct!
Yeah I script more than anything…python, bash, powershell, etc.
Only terrible code I inherit is the stuff I wrote >=3 months ago. I’ll keep saying that three months from now, too.
I can live without documentation and comments, but then you’ve got to write really well-structured, self-documenting code. Which means long variable names (or better: local constants) that describe exactly what’s in them, and function names that describe clearly what the function is for, and readable code that shows what it does.
But perhaps expecting that kind of discipline from people who lack the discipline to write documentation, was not entirely realistic.
Honest question: would an LLM be able to write useful comments in code like this?
use the LLM to generate regression tests for the large file, then start refactoring it
100% I use them a lot to ingest and understand shitty code for me. Of course it’s not perfect, it’s like having a colleague who’s not super strong but has infinite patience for bullshit
It would probably struggle to see the larger picture. I can see it being used to add comments in self-contained functions though without too much difficulty.
Honest question: would an LLM be able to write useful comments in code like this?
It can be better han nothing, but not really. The LLM faces the same challenge that any competent coder does: neither were present to learn the human, business and organization context when the code was first written.
The only experience I have like this is when I wanted to see how the ARMA Life mod was doing certain things, but it was programmed by like 20 different people in 3 different languages. Most of it was in German and French.
It was easier to just to find my own way of doing what I wanted to do.
