DEV Community

Back to basics: Naming

Sadick on June 17, 2018

Between these functions which one do you feel is appropriately named?

Collapse
 
andreandyp profile image
André Michel Andy

Personally, I would use the third option because it looks great along with the if statement.

About the first, I think is not an appropriate name: the function's name says that the function will do some kind of modifications to the input email and then, return it.

About the second, I would use it if email were an object:

if(email.isValid()){
    //do some stuff
}
Collapse
 
lucasmonstro profile image
Lucas Silva

Only if you have an email object :-D

Collapse
 
sadick profile image
Sadick

Interesting. And what would be the structure of that email object.

Collapse
 
andreandyp profile image
André Michel Andy

I think it will be like this:

class Email {
  constructor(email){
    this.email = email;
  }
  get user(){
    //return text before '@'
  }
  get domain(){
    //return domain
  }
  get tld(){
    //return top-level-domain
  }
  isValid(){
    //validate email string given in constructor
  }

}

For a lexical analyzer or something like that

Thread Thread
 
lioobayoyo profile image
lioobayoyo

not meaning to troll or so, but you can have user@ipaddress as a validemail ;)

Collapse
 
albinotonnina profile image
Albino Tonnina

I say the second, isEmailValid.
Canonical is prefix when returning a boolean, others could be is-, has-, does.

Works well:


isEmailValid ? doThis(): doThat()


Collapse
 
katylava profile image
katy lavallee • Edited

Not listed, but I would use isValidEmail. is* is a good way to indicate true/false return value. And if (isValidEmail) reads well.

I would not use validateEmail because I would expect an error message in return, not a boolean.

I would not use isEmail because it sounds weird and unclear to me. I can’t put my finger on why though.

I would not use emailIsValid because I assume there would be a series of functions like this, and I would like their names to all start same.

Collapse
 
moopet profile image
Ben Sinclair

isEmail sounds weird because it's too generic. For most purposes you'll be validating a user's input, and if they put in foo@example.com that may be a valid email address but it's not valid for use as such in the context of your app.

Collapse
 
sadick profile image
Sadick

isValidEmail added. Thanks for the feedback.

Collapse
 
nektro profile image
Meghan (she/her) • Edited

Functionally, I like the second one the best.
I also concur with the

if (email.isValid()){
    //do some stuff
}

However, to go with the object-oriented I'd prefer

public Email(String email) throws InvalidParameterException {}
Collapse
 
sadick profile image
Sadick • Edited

If we were building a lexical analyzer, then this could be one way of modeling that. But in this case we are not. Also note: the question is on naming not structure. How naming affects code readability

Collapse
 
nektro profile image
Meghan (she/her)

Naming wise, I like the second one. But if it was purely my choice I would not make a function to name in the first place and have the constructor do the validation during instantiation.

Thread Thread
 
sadick profile image
Sadick

Does this mean that you will have to create a class and do validation in the constructor for everything in your code that needs validation?

Thread Thread
 
nektro profile image
Meghan (she/her)

For high level objects that take arbitrary input, like an Email or URL, yes. Other things it's not always necessary because the type system ensures everything else is in order

Collapse
 
akshendra profile image
Akshendra Pratap Singh

I like to keep my validation functions in one module, generally named is. So, the call is something like is.email(val). However, if I have to choose a single function, I will name it isEmail. Having valid or validations with is seems a bit redundant to me.

Collapse
 
sadick profile image
Sadick • Edited

Nice catch. Let me also add that as a possibility

Collapse
 
val_baca profile image
Valentin Baca • Edited

prereq question: Is 'email' an actual email or is it an email address?

Calling an 'email address' 'an email' could lead to confusion when you get to actually sending emails.

I'd prefer function isValidEmailAddress(str)

You also probably shouldn't be checking if their email address is valid. Just send the email.

hackernoon.com/the-100-correct-way...

Collapse
 
mlapierre profile image
Mark Lapierre

I think this is the only valid answer so far. ;)

Seriously though, all the rest ignore the fact that validation is being performed on an email address, not an email. The order of the words doesn't matter much if they're misleading words.

And yup, even an email address with a valid format can still be wrong. I get spam all the time because people keep mistyping their email address. It drives me nuts.

So if you do anything at all, send an activation email.

Collapse
 
bgadrian profile image
Adrian B.G.

It returns a boolean answer, so the function should be a question, so it should start with "is" in this case.

I don't think there is a case where "isEmail" and "isEmailValid" are 2 different things, so I will choose the simplest one #KISS.
but ...if you have more features like

function isEmail(e){}
function isEmailRegistered(e){}
function isEmailAdmin(e){}

isEmail will create confusion, and it will have to refactored to isEmailValid.

Collapse
 
alainvanhout profile image
Alain Van Hout

As with most things, it depends:

  • if the function is supposed to return a boolean (i.e. false or true), then isValidEmail seems like the most expressive, in that it leaves the least room for doubt regarding what the method requires as input and what it will return as output
  • if the function is supposed to throw an exception when the string isn't a valid email address and do nothing if it is a valid email address, then validateEmail seems like the most expressive choice

My thoughts on the other options:

  • isEmailValid: this one seems more at home in e.g. user.isEmailValid(), so as a plain function this name adds more ambiguity than is necessary
  • emailIsValid: the same, with the additional concern that it could just as well be the name of a variable/field than a method to be called/queried, so even more unnecessary ambiguity
  • isEmail: very, very vague. Does this refer to a valid email address, a known email address, an object of the type Email, the route via which the user prefers to be contacted ... ?
Collapse
 
alephnaught2tog profile image
Max Cerrina • Edited

My own preference is for is... naming; it makes it clear that it's a boolean. I'd say isEmailValid or isEmail -- but with different contects. isEmail to me implies you are checking whether it's an email at all, but isEmailValid is checking if it is a valid email. A valid email is certainly an email.

Honestly, I'd probably have both, for different purposes. They read as completely distinct.

Collapse
 
stepanstulov profile image
Stepan Stulov • Edited

"If am I developer?". Your code is a set of commands and statements. It doesn't ask its reader questions like how their day is. And everything, that's not some Email class's own function (a'la email.isValid) and that starts with "is" sounds like a question.

Only emailIsValid(email), rain or shine.

Also constructions like "if email is email" make no sense. Of course it is. You need to have a quality (such as "valid") to be used to distinguish good emails from bad ones.

Cheers

Collapse
 
bertilmuth profile image
Bertil Muth

Usually isEmailValid cause it‘s a common convention for functions/methods that return Boolean, and thus will behave predictably for readers.

For the requirements as code project, I would use emailIsValid, as this is the closest you can get to speaking (when email is valid, do this). And I use that to generate documentation from the code.

So there are sometimes reasons to break from the norm.

Collapse
 
lucasmonstro profile image
Lucas Silva • Edited

isEmail is the best approach :) :)

verb + keyword

isValidEmail is redundant. Imagine the following scenario: A string can be a email, but invalid, so, if is invalid, is not an email. So "isEmail" is very good naming.

github.com/typestack/class-validator

Collapse
 
karloabapo profile image
Karlo Abapo

I prefer number 2 because it is specific to the context of returning true or false.

Number 1 isn't bad but it's more appropriate for doing more steps of validating the email other than true or false.

Collapse
 
sadick profile image
Sadick

What about number 3?

Collapse
 
karloabapo profile image
Karlo Abapo

emailIsValid seems to assume the email is already valid.

I try to be more specific when I write; keep the structure close to english or native language to avoid cognitive overload.

Collapse
 
andrewlucker profile image
Andrew Lucker

Acronyms are my preference: "iev"

Collapse
 
sadick profile image
Sadick

iev is not clear at all. How would the next person maintaining your code what iev means?