Write Code That Your Future Self (and Others) Won’t Hate

One goal we should all strive for is to write code that is clean and simple enough that when we look at it six months or six years from now there’s no issue figuring out what it does. Or, as I like to put it, write your code so that your future self doesn’t invent a time machine to keep you from doing something stupid.

This week Javier from Xojo wrote a blog post at https://blog.xojo.com/2020/06/03/using-class-extensions-to-validate-email-and-url-data/ that shows the simple string extensions IsEmail and IsURL. On their face these are nice examples of using Extension to do something useful in Xojo.

Everything is fine until he says this:

“With using the “ByRef” keyword we are instructing Xojo to give us access to the original data; and in that case we will be able to modify the received data through the given variable name in the Parameters field.”

Again, on its face it’s no big deal but this is exactly what my future self would have a conniption fit about. Why? Because when I see IsEmail and I get a boolean back I will assume (as would most developers) that it’s a simple check to see to see if the string is a valid (or valid enough) email. What I absolutely would not expect is for my source string to get modified.

You see, “IsSomething” means true or false in my book. Not, I’m going to mess with your original data. So when your future self sees that there’s an IsEMail method are you going to go look to see the implementation details? Of course not because IsWhatever that returns a boolean seems pretty straightforward and your boss needed the code yesterday.

If you’re going to create a method that massages the data I wouldn’t use an “Is” prefix. Perhaps an extension method that does this should be named “TestAndReturnEMail” because then you’ll at least look at it and go what the hell was I thinking. But then again, using Extends is probably not idea for testing and modifying a string you think is an email. There’s probably a half dozen ways of doing this better.

My general rule of thumb: if you have to look at the guts of a method to determine what it does you’ve already lost. You really think you’re going to remember that IsEmail six years from now mucks about with your original string? I know I won’t.

In my opinion this is the exact wrong place to use ByRef. Feel free to disagree but if I had one of my developers do this I’d be very disappointed.

9 thoughts on “Write Code That Your Future Self (and Others) Won’t Hate

  1. Good comment. I for my part was surprised about a blog post by the same author at the end of May. Xojo deprecates the Xojo framework and publishes new blog posts, which use the “new old” Xojo framework, where there is a replacement for various classes/methods. Here a Xojo.Core.Dictionary was declared especially.

    Take a look at the code in the blog post.
    https://blog.xojo.com/2020/05/20/tip-country-selector-for-web-apps/

  2. Really bad code. I read a few examples of Javier’s code and found them not to be very good.

    There are many regexes for cleaning emails and url. I would have expected a discussion about the different available ones.

    Even the return statement is convoluted. “return (match nil)” is less complex.

    • I’ve never been a fan of the Inline If statement for many reasons. I think it’s hard to read and you can’t put a breakpoint in it. I’d much prefer:

      Return match <> Nil

      or

      if match = nil then
      return false
      else
      return true
      end

      The 2nd one is probably what I’d write in 90% of cases. There is absolutely zero way to get it confused and I can still put breakpoints in it to see if I can catch why it’s not finding a match.

      • I’d definitely prefer: “Return match Nil”

        I like compact and smart code and there is only a very little chance you ‘d have to put a breakpoint in a simple if-then like this.

  3. Good comment, though personally my bigger gripe is that his RegEx is not what I would like to use as

    _.+@…com

    should not be accepted as an email address.

Comments are closed.