86
Self-documenting Code (lackofimagination.org)
you are viewing a single comment's thread
view the rest of the comments
[-] dohpaz42@lemmy.world 7 points 1 month ago
async function createUser(user) {
    validateUserInput(user) || throwError(err.userValidationFailed);
    isPasswordValid(user.password) || throwError(err.invalidPassword);
    !(await userService.getUserByEmail(user.email)) || throwError(err.userExists);

    user.password = await hashPassword(user.password);
    return userService.create(user);
}

Or

async function createUser(user) {
    return await (new UserService(user))
        .validate()
        .create();
}

// elsewhere…
const UserService = class {
    #user;

    constructor(user) {
        this.user = user;
    }

    async validate() {
        InputValidator.valid(this.user);

       PasswordValidator.valid(this.user.password);

        !(await UserUniqueValidator.valid(this.user.email);

        return this;
    }

    async create() {
        this.user.password = await hashPassword(this.user.password);

        return userService.create(this.user);
    }
}

I would argue that the validate routines be their own classes; ie UserInputValidator, UserPasswordValidator, etc. They should conform to a common interface with a valid() method that throws when invalid. (I’m on mobile and typed enough already).

“Self-documenting” does not mean “write less code”. In fact, it means the opposite; it means be more verbose. The trick is to find that happy balance where you write just enough code to make it clear what’s going on (that does not mean you write long identifier names (e.g., getUserByEmail(email) vs. getUser(email) or better fetchUser(email)).

Be consistent:

  1. get* and set* should be reserved for working on an instance of an object
  2. is* or has* for Boolean returns
  3. Methods/functions are verbs because they are actionable; e.g., fetchUser(), validate(), create()
  4. Do not repeat identifiers: e.g., UserService.createUser()
  5. Properties/variables are not verbs; they are state: e.g., valid vs isValid
  6. Especially for JavaScript, everything is const unless you absolutely have to reassign its direct value; I.e., objects and arrays should be const unless you use the assignment operator after initialization
  7. All class methods should be private until it’s needed to be public. It’s easier to make an API public, but near impossible to make it private without compromising backward compatibility.
  8. Don’t be afraid to use if {} statements. Short-circuiting is cutesy and all, but it makes code more complex to read.
  9. Delineate unrelated code with new lines. What I mean is that jamming all your code together into one block makes it difficult to follow (like run-on sentences or massive walls of text). Use new lines and/or {} to create small groups of related code. You’re not penalized for the white space because it gets compiled away anyway.

There is so much more, but this should be a good primer.

[-] RecluseRamble@lemmy.dbzer0.com 8 points 1 month ago* (last edited 1 month ago)

I would argue that the validate routines be their own classes; ie UserInputValidator, UserPasswordValidator, etc.

I wouldn't. Not from this example anyway. YAGNI is an important paradigm and introducing plenty of classes upfront to implement trivial checks is overengineering typical for Java and the reason I don't like it.

Edit: Your naming convention isn't the best either. I'd expect UserInputValidator to validate user input, maybe sanitize it for a database query, but not necessarily an existence check as in the example.

[-] dohpaz42@lemmy.world 5 points 1 month ago

I wouldn't. Not from this example anyway. YAGNI is an important paradigm and introducing plenty of classes upfront to implement trivial checks is overengineering…

Classes, functions, methods… pick your poison. The point is to encapsulate your logic in a way that is easy to understand. Lumping all of the validation logic into one monolithic block of code (be it a single class, function, or methods) is not self-documenting. Whereas separating the concerns makes it easier to read and keep your focus without mixing purposes. I’m very-engineering (imo) would be something akin to creating micro services to send data in and get a response back.

Edit: Your naming convention isn't the best either. I'd expect UserInputValidator to validate user input, maybe sanitize it for a database query, but not necessarily an existence check as in the example.

If you go back to my example, you’ll notice there is a UserUniqueValidator, which is meant to check for existence of a user.

And if you expect a validator to do sanitation, then your expectations are wrong. A validator validates, and a sanitizer sanitizes. Not both.

For the uninitiated, this is called Separation of Concerns. The idea is to do one thing and do it well, and then compose these things together to make your program — like an orchestra.

[-] nous@programming.dev 3 points 1 month ago

This is abuse of the separation of concerns concepts IMO. You have taken things far too far many made it far less readable overall. The main concern here is password validation - and the code already separated this out from other code. By separating out each check you are just violating another principal - locality of behavior which says related things should be located close to each other. This makes things far easier to read and see what is actually going on without needing to jump through several classes/functions of abstraction.

We need to stop trying to break everything down into the smallest possibly chunks we can. It is fine for a few lines of related code to live in the same function.

[-] RecluseRamble@lemmy.dbzer0.com 2 points 1 month ago* (last edited 1 month ago)

If you go back to my example, you’ll notice there is a UserUniqueValidator, which is meant to check for existence of a user.

Oops, right, I just glanced over the code and obviously missed the text and code had different class names. Another smell in my opinion, choosing class names that only differ in the middle. Easily missed and confusion caused.

I don't think our opinions are too far off though. You're just scaling the validation logic to realistic levels and I warn that in practice coders extrapolate too quickly and too often, which results in too much generic code which is naturally harder to understand and maintain than specific code.

[-] olafurp@lemmy.world 2 points 1 month ago

I like the service but the constructor parameter is really bad and makes the methods less reusable

[-] dohpaz42@lemmy.world 2 points 1 month ago

That’s fair. How would you go about implementing the service? I always love seeing other people’s perspectives. 😊

[-] olafurp@lemmy.world 1 points 1 month ago

More or less the same but the user gets passed as a method parameter each time. Validators would be in my opinion a long function inside the service also with named variables like this because it's just easy to read and there are no surprises. I'd probably refactor it at around 5 conditions or 30 lines of validation logic.

I recommend trying out using the constructor in services for tools such as a database and methods for data such as user. It will be very easy to use everywhere and for many users and whatever

const passwordIsValid = ...
if (!passwordIsValid){
  return whatever
}
[-] FizzyOrange@programming.dev -2 points 1 month ago

Oof found the Java developer. No thanks.

this post was submitted on 21 Oct 2024
86 points (86.4% liked)

Programming

17314 readers
160 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Rules

  • Follow the programming.dev instance rules
  • Keep content related to programming in some way
  • If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities !webdev@programming.dev



founded 2 years ago
MODERATORS