This is one of my biggest gripes. Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases. Yeah, you don't need to document the convertMinsToSecs() method, but most real life codebases are full with edge cases, shortcuts, temporary solutions, half-complete reorganizations. So people use this for writing no comments at all, whereas a few words of comments would save hours of investigative work for future developers working on the codebase.
Agreed. For example, comments about Why-do-this, and Why-Not-do-that can be necessary, even if the code shows what happens.
Imagine you're in a taxi, and it suddenly takes the wrong turn, now instead heading towards Surprise-City. Then — you know what is happening. You're going to Surprise-City.
But would't you also want to know Why?
So then it's nice if the taxi driver explains Why: "I buy milk to kitten."
I think the 'Linux kernel coding style' explains comments pretty well:
https://www.kernel.org/doc/html/v4.10/process/coding-style.h...
That's not necessary in every case. But it's true in a good number of them. The code alone can never tell you that - but it's often invaluable during evolution/refactoring.
What are you working around?
What are the assumptions? What limitations?
If it's complicated enough that I'm only understanding it because of the context of the last week, we need the comments. Anything that can speed the reverse engineering in 6 months when it breaks is helpful, because then you can quickly decide that we got different input or if we missed an edge case or whatever.
Someone updating the comments in code that they are updating because they see the comments right in front of them.
Or
Someone going to look through the documentation to see if there is anything relevant about the code they are working on that needs to be updated.
It takes 5 minutes to have thoughtful naming and "this is why because..."
They have done a stellar job at that.
I still believe this to be more or less true.
The important part there is that you have to write good code though.
Advice that relies on people caring about their craft/having the skills to do the work well doesn't scale, so it's bad advice where those things aren't true.
For example, instead of
if (order.version > 1) ...
assign it to a descriptive variable bool orderHasChanged = (order.version > 1);
if (orderHasChanged) ...
IMO this makes it much faster to read and understand, because it says something about the intent. It can also be easier to spot bugs.It's a bit more to write, but I find it makes a big difference when coming back to the code later on, and typing is usually not the limiting factor when writing code.
Time pressure (and particularly with contractors) can lead to some horrific long-term burdens of maintenance.
If for whatever reason you can't link the project properly, as a tip for the future, I've ended up just making a separate copy of the project which included a reference to the uncompiled project.
And in the worst instance I actually used a reverse generated project from the binary. I actually gradually refactored that auto-generated code into more readable code too!
Although, it’s not just programmers fault, the product team is just pushing for changes and never allowing any time for code simplification.
It's kind of nice to know that it's a problem everywhere though. Solidarity.
> It’s fine to have less experienced people working on a large system as long as they have the elders overseeing their work. In the world where senior titles are handed left and right, that is often not the case and it’s how you end up with a very fragile system that is suitable for a replacement as soon as it was built
Then I got to the advice part of the article and had to laugh.
Read the documentation? What documentation. Not a single scrap existed.
Look at the tests? I'd love to, but they never wrote any.
Code comments? Nah.
Use the IDE for intellisense? Great idea except the database models are in a different project so the furthest you can get is the compiled definitions that were copied into this project.
The method that eventually kind of worked was "use the debugger for absolutely everything."
It was honestly one of the most miserable experiences I have ever had.