Figuring out what the code is doing is not the hard part. Documenting the reason you want it to do that (domain knowledge) is the hard part.
Agreed.
And sometimes code is not the right medium for communicating domain knowledge. For example, if you are writing code the does some geometric calculations, with lot of trigonometry, etc. Even with clear variable names, it can be hard to decipher without a generous comment or splitting it up into functions with verbose names. Sometimes you really just want a picture of what’s happening, in SVG format, embedded into the function documentation HTML.
Why the
password.trim()? Silently removing parts of the password can lead to dangerous bugs and tells me the developer didn’t peoperly consider how to sanitize input.I remember once my password for a particular organization had a space at the end. I could log in to all LDAP-connected applications, except for one that would insist my password was wrong. A
trim()or similar was likely the culprit.Another favorite of mine is truncating the password to a certain length w/o informing the user.
Thanks for the tip. password.trim() can indeed be problematic. I just removed that line.
Ew no.
Abusing language features like this (boolean expression short circuit) just makes it harder for other people to come and maintain your code.
The function does have opportunity for improvement by checking one thing at a time. This flattens the ifs and changes them into proper sentry clauses. It also opens the door to encapsulating their logic and refactoring this function into a proper validator that can return all the reasons a user is invalid.
Good code is not “elegant” code. It’s code that is simple and unsurprising and can be easily understood by a hungover fresh graduate new hire.
Agreed. OP was doing well until they replaced the if statements with ‚function call || throw error’. That’s still an if statement, but obfuscated.
I agree, this is an anti-pattern for me.
Having explicit
throwkeywords is much more readable compared to hiding flow-control into helper functions.Good code is not “elegant” code. It’s code that is simple and unsurprising and can be easily understood by a hungover fresh graduate new hire.
I wouldnt go that far, both elegance are simplicity are important. Sure using obvious and well known language feaures is a plus, but give me three lines that solve the problem as a graph search over 200 lines of object oriented boilerplate any day. Like most things it’s a trade-off, going too far in either direction is bad.
Code should be generated from documentation imo
Documentation should be generated from code imo
This means war
Just run both in a loop until it reaches a state of equilibrium.
Or use LLM to generate the doc from all sources you have. Foolproof 100%
Code should be generated from documentation generated from code
I would have liked some comments explaining the rules we are trying to enforce or a link to the product requirements for it. Changing the rules requirements is the most likely reason this code will ever be looked at again. The easier you can make it for someone to change them the better. Another reason to need to touch the code is if the user model changes. I suppose we might also want a different password hash or to store the password separately even a different outcome if the validation fails. Or maybe have different ruled for different user types. When building a function like this I think less about “ideals” and more about why someone might need to change what I just did and how can I make it easier for them.
