I’ve been doing this for years at my current job. It has become a masterpiece of refactoring and comments. They weren’t even asking the right questions. I’m very proud of myself.
So naturally, I’m about to get fired and have the whole thing redone by AI.
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.
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.
Also I only use short variable names inside of loops (for i in iterable…). Is that not how it should be done?
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!
In Go, the recommended convention for variable name length is to be proportional to their scope. It is common to use one or few letters long variables if they are local to a few lines loop or a short function.
There are no comments in the code
At my last job, I was assigned to a project being run by a straight-out-of-college developer who felt that not only were comments unnecessary, they were actually a “code smell”, a sign of professional incompetence on the part of whoever added them. It’s an insane philosophy that could only appeal to people who have never had to take over an old codebase.
I kind of get the idea that code should be self-documenting, but at the same time, there’s so many crazy business rules that comments are basically a necessity if nothing else other than to explain why in the hell the crazed mess that provides the required functionality for the business rules exists.
deleted by creator
I’ll get shit on for suggesting it but this is a great use case for AI: comment the code and generate some basic docs. Even if it’s wrong it’ll give you a sense of where to start looking for flows.
This is the dram. Since the entire codebase is shit, you basically have to rewrite it basically in its entirety.
Which means you can do it with an actual good design.
And if you mess up on something, you have a working version you can consult.
A few years ago I had to port a tool from HTBasic (a proprietary BASIC dialect) to Python. The original source only runs in their proprietary IDE. Of course, no comments whatsoever and a lot of GOTO magic and matrice calculations some of which have no other purpose as to confuse the reader. The variables had only cryptic and meaningless three digit letters. My theory is that they intentionally wrote it in a way that it would be a nightmare to reverse engineer. And they succeeded.
That time I started a new job and my first task was “fix bash”…and then I discovered a multi megabyte monstrosity called “bash.sh”
omfg that’s over 1 MILLION characters 💀 💀 💀
vomit
“Documenting the code base will be your first task for the next month to help show us how well you understand the codebase.”
Translation: please help us understand our codebase. We’re paralyzed by fear.
I’m dealing with this currently. Thank you all for confirming that I’m not crazy
Then you fix 90% of a problem and get blamed when the rest of 10% doesn’t work
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.
“Code IS documentation”
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.
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.
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.
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.
