I'd like to propose weird alternative to this:

  function throwError(error) {
      throw new Error(error);
  }
  
  async function createUser(user) {
      validateUserInput(user) || throwError(err.userValidationFailed);
      isPasswordValid(user.password) || throwError(err.invalidPassword);
      !(await userService.getUserByEmail(user.email)) || throwError(err.userExists);

What if...

      [
          [() => validateUserInput(user), err.userValidationFailed],
          [() => isPasswordValid(user.password), err.invalidPassword],
          [() => !(await userService.getUserByEmail(user.email)), err.userExists],
      ].forEach(function([is_good, error]) {
          if (!is_good()) {
              throw new Error(error);
          }
      });

Also on the regex:

  const rules = [/[a-z]{1,}/, /[A-Z]{1,}/, /[0-9]{1,}/, /\W{1,}/];

No one caught that in all four of these, "{1,}" could be replaced with the much more common "+". A bit odd considering the desire for brevity. I do personally prefer "[0-9]" over "\d", especially considering the other rules, but can go either way on "\W".

I might have also added a fifth regex for length though, instead of doing it differently, if my head was in that mode: /.{8,}/

> The first change I would make is to use named constants instead of cryptic error codes.

But he keeps the cryptic error codes that will go into the logs, or in the frontend where the developer will have to look up the error code. Don't map an error name to u105, just return the actual string: "userValidationFailed".

function isPasswordValid(password) { return /^(?=.[a-z])(?=.[A-Z])(?=.[0-9])(?=.\W).{8,}$/.test(password); }

function isPasswordValid(password) { const issues = []; if (password.length < 8) issues.push("Minimum length is 8 characters"); if (!/[a-z]/.test(password)) issues.push("Must contain at least one lowercase letter"); if (!/[A-Z]/.test(password)) issues.push("Must contain at least one uppercase letter"); if (!/[0-9]/.test(password)) issues.push("Must contain at least one digit"); if (!/\W/.test(password)) issues.push("Must contain at least one special character"); return issues.length > 0 ? issues : ["Password is valid"]; }

I don't like this article, author just added some abstraction and moved the stuff that matters out of the perspective and we just have to imagine that whatever is outside the perspective is perfect.

All source code is self documenting, source code is for developers to read. Computer languages are a human readable version of what the compiler executes and is for the developers, not the compilers benefit. As a developer, I read way more software than I write and if the source is hard to understand then I feel you failed as a developer. Writing is a skill, no less important in software than anywhere else. Properly named functions/variables and easy to follow flow control is a skill that takes years to learn. All developers should keep a thesaurus and a dictionary nearby. If you find yourself writing a lot of comments trying to explain what you are doing in your code, then you probably should refactor.

I agree with most of the article but want to nitpick this last part:

> I’m not a fan of TypeScript, but I appreciate its ability to perform static type checks. Fortunately, there’s a way to add static type checking to JavaScript using only JSDoc comments.

If you're writing JSDoc comments, then you're not writing what the author considers to be "self-documenting code."

I wish the author had explained why they are not a fan of TypeScript. Compile time type-safety aside, as the author acknowledges by implication adding type specificity negates the usefulness of JSDoc comments for this particular situation.

I'm personally a big proponent of "self documenting code" but I usually word it as "code that serves as its own documentation because it reads clearly."

Beyond "I would personally use TypeScript to solve that problem", my case for why ALL comments are a code smell (including JSDoc comments, and in my personal opinion) is:

- They are part of your code, and so they need to be maintained just like the rest of your code

- But ... they are "psychologically invisible" to the majority of developers. Our IDEs tend to gray them out by default etc. No one reads them.

- Therefore, comments can become out of sync with the code quite easily.

- Comments are often used to explain what confusing code does. Which means that instead of fixing the code to add clarity, they do nothing but shine a spotlight on the fact that the code is confusing.

- In doing the above, they make messy code even messier.

I am slightly amenable to the idea that a good comment is one that explains WHY weird code is weird. Even then, if you have the luxury of writing greenfield code, and you still need to do something un-intuitive or weird for really good reasons ... you can still write code that explains the "why" through good naming and separation of concerns.

The only time that I would concede that a code comment was the best way to go about things in context is when you're working with a very large, legacy commercial code-base that is plagued by existing tech debt and you have no good options other than to do your weird thing inline and explain why for logistical and business reasons. Maybe the refactor would be way too risky and the system is not under test, the business has its objectives and there's just no way that you can reasonably refactor in time etc. This happens... but professional developers should ideally treat incremental refactoring as a routine part of the development lifecycle so that this situation is as unlikely as possible to arise in the future.

The picture at the top of article is of a German public library. It has a beautiful, clean architecture. Somehow I don't see how it relates to self-documenting code.

If future "AI" can write code then it should be able to read code and describe what it does at various levels of detail.

I anticipate the day when Gen AI gives us self-coding documentation.

What if the documentation were code? ...