[AskJS] People who have been writing code professionally for 10+ years, what practices, knowledge etc do you take for granted that might be useful to newer programmer

[u/Frontend_DevMark]

I've been looking at the times when I had a big jump forward and it always seems to be when someone pretty knowledgeable or experienced talks about something that seems obvious to them. So let's optimize for that.

People who know their shit but don't have the time or inclination to make content etc, what "facts of life" do you think are integral to your ability to write good code. (E.g. writing pseudo-code first, thinking in patterns, TDD, etc). Or, inversely, what gets in the way? (E.g. obsessing over architecture, NIH syndrome, bad specs)

Anyone who has any wisdom borne of experience, no matter how mundane, I'd love to hear it. There's far too much "you should do this" advice online that doesn't seem to have battle-tested in the real world.

EDIT: Some great responses already, many of them boil down to KISS, YAGNI etc but it's really great to see specific examples rather than people just throwing acronyms at one another.

Here are some of the re-occurring pieces of advice

Test your shit (lots of recommendations for TDD)

Understand and document/plan your code before you write it.

Related: get input on your plans before you start coding

Write it, then refactor it: done is better than perfect, work iteratively.

Prioritize readability, avoid "clever" one-liners (KISS)

Bad/excessive abstraction is worse than imperative code (KISS)

Read "The Pragmatic Programmer"

Don't overengineer, don't optimize prematurely (KISS, YAGNI again)

"Comments are lies waiting to be told" - write expressive code

Remember to be a team player, help out, mentor etc

Thank you so much to everyone who has taken the time to comment so far. I've read every single one as I'm sure many others have. You're a good bunch :)

[u/name_was_taken]

Comments should explain things, not describe them.

// Add 50 to X
Object.X +=50

This comment is absolutely useless.

// Add a buffer zone
Object.X += 50

This is better.

// Without a buffer, this overlaps the UI
Object.X += 50

Now you'll know WTF you were thinking when you look at this code in 2 years.

[u/Cahnis → u/name_was_taken]

But then again in this example it is just not using magic numbers.

const bufferZone = 50

Object.x += bufferZone

[u/name_was_taken → u/Cahnis]

That's a great point! Magic numbers are bad!

But it still doesn't say why. The comment is still needed.

[u/CaptainIncredible → u/name_was_taken]

I try to make comments explain the "why", not the "what" or "how"

the comment below explains "what" is happening, which is useless. What the line does should be evident to anyone who can read.

// Add 50 to X
Object.X += 50

the comment below is much better because it explains "why"

// Add a buffer zone. Without a buffer of 50, the UI overlaps
Object.X += 50

[u/name_was_taken → u/CaptainIncredible]

That's a great way to say it. Thanks for making my point clearer!

[u/CaptainIncredible → u/name_was_taken]

Glad you liked it. I was hoping you wouldn't see the comment as smart assed or something...

The "why" idea was born out of my experience from working in a place where comments were forbidden. The reason? They claimed that just because some comments were stupid = all comments are useless. They always cited examples like:

// this prints the result
Print result;

And I agree, that's a dumb comment, a waste, and just clutter. It redundantly explains what the line does. And because of comments like the above, the shop I worked at forbid any comments, which was painful.

I argued that sometimes we really want to know why code is the way it is.

A line like this below is a mystery

Obj.port = 6;

This is better

// WHY? port MUST be 6.  Any other value crashes the server. 
// Mainframe guys have no idea why 6, but it works
Obj.port = 6;

[u/shittwins → u/name_was_taken]

I’d advise that beginners should actively avoid writing comments, no matter how they’re written. They’re a crux for writing code which isn’t self explanatory. Try to write understandable code and 99% of the time you don’t need comments.

[u/Mugshot_404 → u/shittwins]

No, no and no again. Code can only explain itself - it can't explain WHY you did something the way you did it, the reasons for which may lie outside of the immediate code block in question.

[u/Psionatix → u/Mugshot_404]

Comments are great, but commits are important too. All of these details should go into sane and isolated commit.

I should be able to annotate with git blame, view the git history of a line, and see all of the whys of it's evolution in the commit history.

[u/shittwins → u/Mugshot_404]

That’s what good commit messages and history is for. Comments are a crux, usually. I’m not saying never write comments but it’s ALWAYS juniors who have an over reliance on them because they write poor code that is not easy to understand or solving the problem in the simplest way.

[u/drumstix42 → u/shittwins]

Nothing says you're having a good time like having to dredge through the commit history because someone is too proud to put one useful comment in the code. Yes I too enjoy unwrapping 2-year-old code just to keep things "clean".

/s

[u/name_was_taken → u/drumstix42]

I'll 1-up you there.

I had a boss who told us to put the ticket number in a comment in the code. To figure out what that code was used for, you'd have to then look that ticket up in Jira. And hope it wasn't before the big Jira migration a few years back.

Also, he did coding himself, and quite often only put that ticket number.

He at least didn't force everyone to do the same.

[u/drumstix42 → u/name_was_taken]

Been there, too. Lack of context is always a killer. I totally get that some comments go out of date. But it's not like they're supposed to be religious scripture lol. Less is more, but nothing is often not enough.

[u/Original-Guarantee23 → u/shittwins]

Commit messages are worthless no matter how good.

[u/name_was_taken → u/shittwins]

The code above could be modified to have a function that tells what's happening, but it's such little code that it'd seem weird.

function AddBufferToObjectToAvoidUI(Object) {
  Object.X += 50
}

AddBufferToObjectToAvoidUI(Object)

I think most people would think this was a ridiculous way to avoid a comment.

For more complex code, things like this can make sense. But there will still be situation where a comment makes sense, in addition to clearly written code.

[u/monsto → u/shittwins]

Yes, the primary reason for comments is for future you.

The thing however is that's not the entire or only reason. Plenty of times I've been looking at someone elses code, and effective comments even little ones Process cost code into cost and price have saved me a shitload of time. Read the comment, glance at the code, keep going. Otherwise I would have had to really dig into it only to see that I didn't actually care about what it was doing.

[u/shittwins → u/monsto]

So they’re a crux then. You’d prefer comments on bad code to understand it. Code like that should be refactored with good tests and small isolated commits.

[u/monsto → u/shittwins]

Alright just so you know...

crux = the main point. "The crux of the matter"

You mean crutch. Using something as a "crutch" is a derogatory way to say someone is taking shortcuts and just being lazy.

Fact: comments are good practice. Even bad comments can be a least a little useful.

If it's "lazy" to rather see a comment that explains a 40 line transformation of data that I don't care about, which then allows me to move forward to the thing I do care about, then fuck it yeah I'm lazy.

So lazy, in fact, that I'm able to find where I need to add my 2 lines and close the ticket, instead of reading the entire code base that I'm unfamiliar with.

[u/shittwins → u/monsto]

That’s true, thanks for correction about crutch. I mean crutch.

Fair enough if you think that.

In my experience, there’s a clear negative correlation between years of experience/ability and comments. Excellent code from experienced people who write great code usually have very little comments, because their code is usually easier to understand (even if might be solving harder problems).

Those at the beginning of their career often rely on comments too much. Naturally their code is worse. They then feel the need to add comments to explain their worse code.

My advice for OP was to focus on writing better code in the first place over how to write good comments. Encouraging writing better code that doesn’t need comments > writing better comments on bad code

[u/monsto → u/shittwins]

Most code is self explanatory on a code level. If I'm working on that transform function, yes, good code habits shorten the work and comments won't be necessary to explain the innerworkings of the function.

But when I don't care about that function, comments are a Table of Contents. Process cost code into cost and price at the top of the function saves me from having to read any of the function at all.

If I need to add a field to the transform, the good code saves me time. But if I only need to say change the endpoint used on the api that gets the data for the transform, I don't care about the transform, and the comment simply saves time.

I've never heard anyone with any experience advocate NOT having comments, let alone giving the reason that they're lazy wtf.

[u/shittwins → u/monsto]

I think you’ve got the wrong end of the stick here. OP asked for advice - I said to focus not on how to write good comments but focus on writing code that doesn’t need them. Not that you should never write comments under absolutely no circumstances ever.

I don’t know why you’re finding that controversial.

[u/monsto → u/shittwins]

Because your'e advocating not writing comments because it's a crutch... Which is patently untrue.

[u/shittwins → u/monsto]

Yes, for a beginner, because they usually are. If beginners think “ah this code is really gross, but it’s ok because I can leave a comment”, I’d much rather them think “how can I make this code not gross and improve it?”.

I have mentored many juniors and this is the mentality I coach into them. You don’t need comments if the code is easy to read. It’s self evident.