Comment by bluefirebrand | Hacker News Reader

Comment by bluefirebrand | Hacker News Reader

Parent Full thread

This is a great article. I felt like it was describing a job I recently left, especially this piece:

> 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.

> Code comments? Nah.

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.

> Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases

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...

my priority for comments is that they should answer "why?" and "why not?" questions. Why does the method/function do it this way? Why didn't it choose that other, perhaps more obvious route?

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.

Why does this code exist?

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.

Yah, and what's gross is when your team-mates criticize you for leaving comments at all. Let alone a lengthy discussion on why.

While I agree to some extent, the problem with comments is that they need to be maintained in order to be helpful: code comments - updated when the code changes, general comments - when the context changes, etc. This is a work in itself: developer has to remember to do it, reviewer has to remember to look for it. In my experience, people tend to forget to do it or just don't bother, which means that someone else finds himself with a contradictory, outdated, confusing comment further down the road.

Sure but which is more likely:

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.

Somewhat surprisingly, it depends. For instance, in our case application support is responsible for/interested in the documentation, and they make sure that developers create/update the relevant documentation for each of the release items. Stale comments, on the other hand, need to be identified and addressed in code reviews, and in practice we're not always good at that.

I'm really grateful for my current team because of this.

It takes 5 minutes to have thoughtful naming and "this is why because..."

They have done a stellar job at that.

> good code is self-documenting

I still believe this to be more or less true.

The important part there is that you have to write good code though.

So, the advice is bad, as most people (including myself, no doubt), will write mediocre code, just by the shape of the distribution (assuming it's normally distributed, which is a strong assumption, but without data it's probably reasonable).

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.

You come a long way with avoiding direct calls in "if" clauses and similar, using descriptive variable names, and not trying to be clever for the sake of being clever.

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.

Also in lots of cases you are in a hurry to meet that deadline that compromises code quality. Better to leave a comment in this case than nothing

Yeah, especially if you do something weird. People have often done weird strange stuff that made sense when I finally figured out the reason.

Time pressure (and particularly with contractors) can lead to some horrific long-term burdens of maintenance.

I think Uncle Bob got cancelled /s, but politics aside, I don't think he was necessarily wrong about good code documenting itself, but it came with a lot of direction about what then exactly constitutes good code. If people don't bother to hone the skills of good types and methods, well named and with clear responsibilities, of course they're not clearing the bar to drop the comments. Having grown more senior, I believe I have gotten a little better at expressing meaning and intent through the code itself, and I'm surely writing a lot less comments because of it, which seems a win overall.

Use the IDE for intellisense? Great idea except the database models are in a different project...

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!

I actually tried to make a separate copy of the project once but the project had to be in a specific folder on the hard drive. Trying to put it somewhere else broke so many hardcoded absolute paths that I gave up fixing them all.

I’m currently in exactly that situation. No comments on tiny workarounds, no high level docs on any feature, any kind of code criticism interpreted as personal attacks. I’ve worked at teams where I can easily add 1000+ lines of well tested and incremental code a week, but here I can barely reach 200.

Although, it’s not just programmers fault, the product team is just pushing for changes and never allowing any time for code simplification.

Gaming company in San Mateo? Lol

Nope. Different industry and country even!

It's kind of nice to know that it's a problem everywhere though. Solidarity.

Reply on news.ycombinator.com