Discussion on: Bad Habits of Mid-Level React Developers

[JoelBonetR 🥇]

It's the first time in my life that I read something that "documenting your code is bad". You guys surprise me more every day 😆

Of course you need to think before writing a function, and as best practice you'll probably re-write this function splitting it in two or three because you forgot to apply the S on SOLID (single responsibility).

Remember that the first half of a developer job is to make the code work, the other half is to make it maintainable, readable, documented and tested.

[Rense Bakker]

Yes, good code doesnt need documentation. Read Clean Code by Martin Robert. If your code needs documentation, its not easy to read/understand and is therefor bad code.

[JoelBonetR 🥇]

That describes a concept not a reality. The maximum perfection in a team would be to understand each other's code to the perfection, all with the same level/amount of knowledge and working together for years.

In a real life project working in a team, usually you'll get different expertise levels, there's people rotation and you'll have to maintain the code for long time.

I can code a function composition inside my code and the junior will come and say "bruh, WTF". If we can take the time and resources to raise the seniority to a given "minimum" level for the project it would be fine (I guess, never saw it IRL)..

But even that, there's no single pattern or best practice other than documenting your code that can release you from the burden of remembering everything in a future stage.

Let's say you work 5 years in a project and someone new comes to it. Understanding what it does in the big picture is a matter of reading function names (if the codebase is good).

i.e. getUserId(user) will obvious get the user ID, probably from a user object. If you use TS you can see that user ID is a number and that user param is a user object. That's all the knowledge you can take from the declarative part of the code.
Usually you'll see something like:

const getNewNickname = (user) => generateNickname(randomize(capitalize(concatNameAndSurname(user))));

Adding doc would be something like:

/**
   * Generates a new random nickname based on the current user name and surname
   * @param {Object<User>} user 
   * @returns {string} Nickname
   */
  const getNewNickname = (user) => capitalize(generateNickname(randomize(concatNameAndSurname(user))));

Isn't that beautiful?
Let's get a step further adding function composition:

const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);
const getNewNickname = compose(capitalize, generateNickname, randomize, concatNameAndSurname, user);

Can everyone predict what will that do exactly without having to think for some seconds? I can honestly say that a quarter of my current team wouldn't.

Let's add Doc to it:

 /**
 * Executes a sort of functions from right to left, passing the output to the next function
 * @param  {...any} fns functions
 * @returns {any} execution result
 */
const compose = (...fns) => x => fns.reduceRight((y, f) => f(y), x);

/**
 * Generates a new random nickname based on the current user name and surname
 * @type {string} nickname
 */
const getNewNickname = compose(capitalize, generateNickname, randomize, concatNameAndSurname, user);

Isn't it better, faster and quickier?

So i've lost less than a minute to avoid others in the team not loosing a couple of them in a future.

And we just saw the declarative part, on the imperative part scoped in helpers and functions could be harder to catch up things quickly as they'll have procedimental code with conditions, loops and so on, and here is where doc shines most.

[Rense Bakker]

Clean code is a concept that was born from a shit ton of practical experience... Uncle Bob has what? 40 years experience in the field? And it's not like he's alone, or that the concept of clean code wasnt adopted and put in to practice for the past 14 years...

You can claim all you want... No junior developer is going to understand what your JSDoc comments really mean, or know how to use it properly themselves. With typescript they have no choice... But more importantly, they don't have to care at all because Typescript does type inference automatically and it will just tell them what they're doing wrong if they try to assign the wrong type to a variable or function :B no understanding JSDoc required and a bunch of other tools and VS code plugins that you need... I have the complete opposite experience than what you claim... The junior devs I have encountered found Typescript very easy to learn and use.

JSDoc, like PHPDoc is archaic, from a century before we had modern type systems and stems from Javadoc which is even more archaic...

I agree, the example you give is a horrible obfuscation of logic that you should not do at all. If someone changes what is returned by one of the functions in your composition and doesnt update the JSDoc for it, Javascript is going to crash in runtime and I would love for you to let a junior dev try to find and fix that runtime error with your function composition. If you work with 10 devs, I guarantee atleast 5 of them are not going to care much about updating code comments when they're writing code. I much prefer devs who try to write clean code, instead of trying to explain their mess with JSDoc.

[JoelBonetR 🥇]

So, to recap, you'll use TS always instead JS, isn't it?

[Rense Bakker]

I am using JS since TS is just superset of JS, but yes, for typesafety and to avoid a million runtime errors everytime you forget something, I will use TS until something better comes along.

[JoelBonetR 🥇]

So you took a decision based on other decisions you made before (learning TS and ignoring vanilla JS as much as possible).

“If the only tool you have is a hammer, you tend to see everything as a nail.”

Taking in mind that TS does not check types at runtime and also knowing the context where you are working on (in this case React), where runtime errors are mostly due to some API error (the backend guy forgot to add some property, the swagger says that in this contract you should get a string but instead you got an integer and so on) you'll face exactly the same amount of runtime errors either using one thing or another but hey, those are your projects, not mine.

[Rense Bakker]

The amount of assumptions you make about my work experience with other languages shows how narrow minded you really are.

There are ways to avoid runtime errors from API changes, but i'm sure you have a very strong opinion about those tools as well and frankly I have come to the conclusion that its utterly pointless to discuss these things with you.