Writing expressive code

I was just writing a small piece of javascript code, and one of the things I need to do is get the contents of a node which has a span and a text node. The idea was to get the contents of the span, and the rest of the text in two separate variables. My first instinct was to grab the contents of the span, and then grab the contents of the text node that followed the span, but I discovered that there were actually two different text nodes. One was empty, and the other one had the text I wanted to get. Since this is an action that needs to be repeated a number of times and there is no guarantee that there will always be two different text nodes, I decided to just grab the content of the span, and then the full textContent of the parent element, and just remove the text in the spam from the full text.

When the time came to remove the contents of the span from the full text, I decided to use the slice method of String. This method takes a starting offset, and an ending offset. So, if I have the text “Hello”, and I slice starting at index 1, I would get back “ello”. In my particular case, the full text starts with a code, and then a description. For example, “ABC Some description”. The idea is to get a variable with the value “ABC”, and another one with the value “Some description”. So, all I had to do was slice the full string starting at the index equivalent to the length of the code string, which is what is contained in the span element. But if you pay attention, you will realize a small problem: I would end up with the value ” Some description”. Notice the leading space at the start of the string.

At this point, many programmers would just call slice with the starting index set to the length of the code string plus 1. This gets the job done, but later in the future you, or some other programmer who inherits your code may wonder why you added 1 to the length of the code string used as the starting offset. Some programmers will tell you that that is what comments are: to provide clarification on situations like this one. But I’m recently of the idea that comments in code are often just noise. And yes, I know this goes against most advise you’ve heard around. I’m not saying comments are bad, I’m saying if your code needs comments, your code is probably bad. And by “bad” I mean, not expressive enough.

It turns out there is a better solution for this: use trim(). The trim method is very expressive. It tells you “Hey, this string may or may not have leading or trailing spaces that I don’t want, so I will remove them”. Yes, it says all that in just 4 characters…

The point is, if you need to write a comment in your code, pause for a second and think “Is there a way to say in code what I’m trying to say in comment?”

Composing functions with PHP

Composition is a great way to build complexity. You take small functions and combine them to build more complex functionality. For example, suppose you have the string “$12,000” and you need to take 10% off that and represent it as a money string. You could build a single function that does exactly that, and then go about your life until you discover that your function has a bug in it, or that it can’t be reused for a similar problem, like taking 15% off the string, instead of 10%. At this point you may be tempted to alter your function to take a parameter indicating the % to subtract from the number. This adds more complexity to a function that is already doing more than it should, and it doesn’t guarantee you won’t have to change it later on again. For example, what if now you need to be able to do that for any arbitrary money string, not just “$12,000”?

The answer is composition. Instead of writing a single, bug-prone, function that does way more than it should, you should write smaller functions that are easier to reason about, maintain, and which are more likely to be bug free.

Assuming you are guaranteed 100% that the input will always be in the right format, meaning, a formatted number preceded with a dollar sign, no decimal point, and that uses commas to separate thousands, you could write the following functions:

stripDollarSign
removeThousandsSeparator
takePercentageOff
formatAsMoney

The first function would take a string, and return a string but without the dollar sign. It would be trivial to write, and almost guaranteed to be bug free.

The second function takes a string, removes the commas from it, and returns an integer. (Remember we are guaranteed the right format, so we can assume the remaining string can be cast into an integer). This function is also trivial to write and almost guaranteed to be bug free.

The third function takes an integer, subtracts a percentage from it, and returns another integer.

The last function takes an integer and formats it as a money string. Now all you have to do is call the functions one after the other:

formatAsMoney(takePercentageOff(removeThousandsSeparator(stripDollarSign("$12,000"))))

But this looks rather ugly, and it is hard to read. What we need is to be able to combine those four function into a single function that does what we want. That is what composition is.

Composition comes straight from functional programming, and it is such a great idea that I wanted to bring it to the PHP world, so I wrote the following function:

<?php
/**
 * Compose two functions.
 *
 * Returns a new function that calls $a after $b.
 *
 * @param callable $a
 *   The function to apply last.
 * @param callable $b
 *   The function to apply first.
 * @return callable
 *   A function that calls $a after $b.
 */
function compose(callable $a, callable $b):callable {
  $composed = function ($param) use ($a, $b) {
    $partial = call_user_func($b, $param);
    $whole = call_user_func($a, $partial);
    return $whole;
  };

  return $composed;
}
?>

This function is far from perfect, but it is a starting point. I decided to only take 2 function as parameters, instead of an arbitrary number of functions because you only ever compose two functions. When you think you are composing more functions, such as in our example, you are really composing them in pairs. You first compose the first two functions, and the returning function is composed with the 3rd one and so on.

I was so happy with my compose function that I considered putting it in packagist, but I think the Functional PHP package by lstrojny is a better alternative since it includes its own version of the compose function. The one thing I’m not so happy about is that the version in Functional PHP doesn’t seem to be able to take function names as parameters. This may limit the functions that you can pass to it to compose.

You may have noticed we didn’t solve the issue with wanting to take a different percentage amount off of the original amount. This can be solved easily with another concept from functional programming: partial application. But I will leave that for another time.

Log From Within Puppeteer page.evaluate

A couple of days ago I was trying to find out why a small puppeteer script wasn’t working correctly. I wanted to see what was going on within a callback function passed to page.evaluate. The problem is that page.evaluate runs in browser context, so the console.log calls you make will log inside the Chrome instance, and won’t reach your console. Luckily, puppeteer has a way to bring those logs to your console:

page.on('console', function (msj) {
  console.log(msj.text());
})

The msj argument on the callback is an instance of consoleMessage which has a few nice methods that let you work with console messages. One of them is the type() method, which returns the type of message that was logged. This lets you filter out a bunch of warnings that some pages may generate:

page.on('console', function (msj) {
  if (msj.type() === 'log') {
    console.log(msj.text());
  }
})

I was pleased to find that puppeteer has this nice method to bring console messages from browser context to script execution context. This made my work a lot easier.

In Git, Say What You Did, Not How

Writing good commit messages is something I sometimes obsess over. To me, commits need clear messages that, when read, tell a story about how the project has been evolving. I get rather annoyed when a teammate commits things like “Implements X’s feedback”. This tells nothing about the commit, nor about the history of the project. Over the years I’ve found that a good rule of thumb is to describe what you did, not how. This is better explained with an example:

Say you are fixing a bug that requires you to change a multiplication operation for a sum operation. Instead of writing

“Changes multiplication to sum”

You could write

“Fix the total price calculation. Wrong totals were given.”

This way anybody reviewing the git log can see right away that in that particular commit a bug in total price calculation was fixed. The first message doesn’t tell a story about the project, it tells a story about the code. You don’t want that in your commit messages.

Another thing I’ve learned is that commit messages aren’t always about the thing you are trying to fix or implement. For example, I recently had a teammate report to me that an form error was not displaying in the right place. This was for a floating form that opened via a button. When the user didn’t enter information in a required field, the form would disappear and the error message would be displayed in the main page instead. This was confusing to say the least.

My job was to display the error message right there when the form was open. I saw that the form already implemented HTML validation for some of the required fields, so it was a good idea to do the same for the ones that it didn’t so the experience remains consistent. I did just that, and when the time came to write a commit message I was tempted to say something about the commit being for fixing an error display issue. But when I thought about it a bit more, I realized that was not what the commit was about. The commit was about adding HTML validation to fields that were missing it. So I wrote that instead:

Implement HTML validation for fields that don’t have it.

But I’m guessing future me may want to know “why” this was needed. So, I made future me a favor and added a longer explanation as well as the initial “heading” message above:

“We want to show errors about missing information for X and Y input types when they are required right on the form instead of having the form refresh the page with an error message.”

I’ve found that sometimes it is useful to explain why you did what you did as part of the commit message, but I’m always careful to put that in a paragraph bellow the commit heading which explains in short words what I did. I don’t always add a commit message body explaining why I did what I did. I usually only add a commit message heading that explains what I did in as few words as I can, but whenever I find it necessary, I add a commit message body without worrying about commit message length.

No Charge. Thank You.

A few days ago I received a message asking me if I could take a look at a poorly taken photo of the screen of a laptop stock in BIOS with the text “What should I click here?” My reply, “I can’t see anything, please take a better picture and send it to me”…

A couple of minutes later a new photo come through — clearer this time. “Just press f10 to exit”, was my reply. A minute later: “It’s stock on the same place…”. At this point I realized something bad was going on. Either disk failure, or worse, completely broken laptop. “Please drop it by the office tomorrow morning. I will take a closer look”.

The next day I could confirm my suspicions: the HD was failing. I decided to drop the HD at a repair center just so they could confirm my diagnose. They did.

A few hours after dropping the disk off, I returned to pick it up. They explained to me that the disk had a few errors, and a few bad sectors, which I already knew. They did exactly what I had asked them for, which was to confirm my own diagnose. At this point I pull my wallet out, and ask “What do I owe you?”. “Nothing”, they said. “We didn’t fix the disk”. Which is true, they hadn’t fixed it, but I didn’t asked them to. I asked them for one thing, and they did it. Why would they not charge for it? Is their time worth nothing?

At this point I realized that many people from different lines of work act the same way. I can see two philosophies here:

1) You charge for your time, which means that even a small consultation will generate a fee.

2) You charge for results, which means no matter how much time you spent on something, if at the end you can’t deliver a result, you won’t charge anything at all.

People want results. They want you to fix their stuff, or to make something for them, and if you don’t then there is no reason why they should pay a dime. But why?

This isn’t always the case. For example, if you go to the doctor, they will diagnose you, and charge you for it. They haven’t cured you. Sometimes you can’t be cured, but they will still charge you. If you go to a mechanic and they have to scan your car, they will charge you for the scanning. Regardless of whether they will fix your car or not, they will charge you for using their scan. But if a you call a plumber, and the plumber can’t unclog your drain, you sure won’t pay a dime.

A few years ago a restaurant owner asked me to “put them on the internet”. We talked for about an hour about what we could do to “put them on the internet”, and after some time he asked for a price. I gave him an estimate, to which he replied “So, you will charge me this amount just for thoughts?”. He clearly didn’t have an understanding of how the web, and search engines work. I got up and left. I wasn’t about to embark in a project with a client that undervalues the work I do.

Why is it that for some people it is OK to end hours of work with “No change. Thank you”?

At a reunion party a lawyer and a dentist are having a conversation, and at some point the dentist asks:

– Sometimes people call me to ask what they could take for a toothache, or if they should use X or Y toothpaste. Should I charge them?

– You are a professional in the health industry, of course you should charge. Every consultation generates a fee.

– Wow! You are right. Thanks!

They continue talking a bit longer until they meet other old friends. The next Monday the dentists arrives at his office to find an invoice from the lawyer for consulting services. He remembered the lawyer’s words “Every consultation generates a fee.”

Remember: dataset Values are Always Strings

I was doing some updates on a slider component a few days ago, and came up with an odd behavior: it would suddenly start using huge numbers as an upper boundary.

At work we use a few different components that were written in a hurry some time ago. Many of them have been updated, refactored, and pretty much maintained over time, but the slider hadn’t been touched since it was first created. We realized it was outdated, and needed some updates, so I set up to do that.

The component is a simple range selector. It has a minimum and maximum values and users can select any range in between sliding a handle on each side of the slider. The minimum and maximum values come from the server and are kept as data attributes on the slider. We use them to make calculations about the values in between when the user adjusts the range. As part of the calculations we do, we need to add the maximum value to a number we’ve previously calculated. Since values from dataset are always strings, the addition was becoming a concatenation instead, and it was producing larger numbers than expected.

When I realized that, I knew I had to make a note here in this blog to remind myself, and all of you, that values from dataset are always strings.

As a bonus tip, remember that explicit is always better. Which of this is the best way to handle this situation?

3 + +"12";
3 + parseInt("12")

Both are technically correct, and produce the expected result, but the first one is confusing. Yes, it looks “cool” to show that you know how to cast a string to integer using the plus operator, but it is harder to read, and to figure out why you are doing that. A less experienced programmer might look at that first statement and “correct” it like this:

3 ++ "12";

Which is wrong.

Things become even worse when you introduce variables:

3 + +apples;

At some point you may forget you need to cast apples to integer, and just remove the plus sign. At that point you will be introducing a silent bug. Good luck with that.

On the other hand

3 + parseInt(apples);

is very explicit. When you see that you know right away that you want to turn apples into a value of integer type. The chance of you, or another less experience developer removing the parsing function are far less.

Mind your Parens

A couple of weeks ago I was notified of a bug in one of the scripts I wrote some time ago at work. The bug wasn’t apparent, and for the most part it was harmless, except that it was preventing one page from the website from rendering. Someone else had recently added a script that was failing to load because in jengascript everything fails after an unhandled exception. So, what was the problem?

I wrote a function that expected a DOM element as parameter, and if something else was given to it, I wanted it to return early. I decided to implement this using the instanceof operator.

function doStuff(el) {
  if (el instanceof HTMLElement) {
    // do the stuff here.
  }
}

That works, but now all your code is unnecessarily a level of indentation too far. That can be easily fixed. Check for the opposite and return if true:

function doStuff(el) {
  if (!el instanceof HTMLElement) {
    return;
  }
  // do the stuff here.
}

This is much better, and it seemed to work. Had I had unit testing set up and a good set of tests I would have caught the error, but I didn’t. No one else in the team did either, and this buggy code shipped to production only to fail months later when the script file was introduced somewhere it wasn’t supposed to. At that point the function started receiving null as parameter, and shit broke.

So, what was the cause?

The function only seemed to work because the if statement would always be false. This meant passing an actual HTMLElement to it would run the script and things appeared to work, but passing null would fail to return early. The function tried to do its stuff but it couldn’t call methods of HTMLElement on null. An exception was raised, and then everything after that failed to run. We were left with a BSOD.

The solution.

The solution is rather simple. Wrap shit in parens…

function doStuff(el) {
  if (!(el instanceof HTMLElement)) {
    return;
  }
  // do the stuff here.
}

This way we would be negating the result of el instanceof HTMLElement, not just el itself. Please, learn from my stupid mistakes that have the potential to break production sites, mind your parens, use them, they are free, add clarity to code, make it more explicit, and highlight intention. Plus, they add no overhead.

Use the Pipe

A few days ago I was trying to extract a piece of data from certain lines of a CSV file. The file is a list of inventory items. Some of those items have a special field set to the value “R”. This lets us know that those items can be purchased after their loan term has expired. The CSV file has different fields for each item. Each line in the CSV file represents an item. So, identifying those special items was quite easy with sed:

sed -n -e '/"R"$/p' file.csv

I knew the special field was the last item in each of the lines of the file, and that command above would give me all the lines of items that I was interested on. However, each line has a lot of information that I didn’t care about at the moment. I was interested only on the stock number of each item, which follows a pattern that can also be searched for using a regular expression. I wanted to get a list of stock numbers, so my first instinct was to check the man page for sed to see if there was a way to print only a specific part of the line that matched the address in the p command. A quick scan through the man page quickly revealed that there wasn’t a real way to do what I wanted. How was I supposed to do it? Did I have to write a small program to do it?

I always keep in mind the unix philosophy: <<Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new “features”>>. But I think keeping it in mind is not enough. It has to be part of your way of thinking. I was reminded of this by an answer in stack overflow. Composition is a fundamental part of how the shell works. You run a program, take its output and use it as input for another program:

sed -n -e '/"R"$/p' file.csv | grep -o "regexp" > output.txt

The day after, when I wanted to count the lines that matched a pattern in a file, reaching for the pipe was my first instinct. Rather than wanting a single program do everything I wanted, my first thought was: What programs can I combine to achieve this?

sed -n -e '/"R"$/p' file.csv | wc -l

The unix philosophy is something I’ve been thinking quite a lot recently after a few months ago I realized that at work we were writing functions that tried to do a ton of things. That is when I remembered that a function should do one thing, and one thing only, and do it well. This is also the philosophy behind functional programming where composition is THE WAY to do things. But until we’ve baked this into our way of thinking, just knowing it won’t do us any good.

Use the pipe.

The Boring Stack

I think  someone finally put in writing something I’ve been thinking for  some time: https://justmarkup.com/notes/2020-01-14-boring-by-default/

To me it makes a lot of sense to start any new project with a blank static html page, some old fashion CSS and the vanilla js framework. Over complicating things seems to be the norm nowadays, and it’s leading us to an increasingly fatter web.

I remember back when I first started learning about web development there was a strong push for fast websites in terms of page load, and interaction. File size and external resources was something you were trying to keep as low as possible. But things quickly got out of control with the rise of javascript frameworks. Suddenly there were many different javascript frameworks and developers started loading them in their pages, sometimes more than one at the same time. The fact that libraries had to implement a no-conflict function is a testimony of this issue.

Many new web developers compensated their lack of experience with a ton of plugins. Inexperienced programmer quickly began creating fat websites where simple static HTML would have sufficed; no plugins required. WordPress development, for example, is based completely around the use of plugins, many of which load their own version of X library. It became common to see websites that loaded 2 or more version of jQuery on the same page because different plugins required different versions. At some point it seemed to me that a WordPress developer was just someone who could login to the admin panel, and install a bunch of plugins. And the plugin market didn’t make it any better.

Plugin makers, in an effort to capture as many sells as possible, ship plugins with a gazillion features out of which you will only use 1 or 2. The thing is, developer Y will require a different 1 or 2 features of the same plugin, so having them available increases the chance of a purchase.

Then came heavier frameworks like Vue and React. The problem is not the frameworks themselves, but developers who just use anything new and fancy for the sake of appearing cool, and in with the current web trends. Add to all of this the ton of tracking scripts that websites add plus the ads and you have a mess. No wonder people have been talking about a bloated web for years.

I hope one day we will realize the error in our ways and get back to the right path. But for now, do me a favor, be boring…