I’ve been working with JavaScript on and off since the late nineties. I didn’t really like it at first, but after the introduction of ES2015 (aka ES6), I began to appreciate JavaScript as an outstanding, dynamic programming language with enormous, expressive power.

Over time, I’ve adopted several coding patterns that have lead to cleaner, more testable, more expressive code. Now, I am sharing these patterns with you.

I wrote about the first pattern — “RORO” — in the article below. Don’t worry if you haven’t read it, you can read these in any order.

Elegant patterns in modern JavaScript: RORO

Today, I’d like to introduce you to the “Ice Factory” pattern.

An Ice Factory is just a function that creates and returns a frozen object. We’ll unpack that statement in a moment, but first let’s explore why this pattern is so powerful.

JavaScript classes are not so classy

It often makes sense to group related functions into a single object. For example, in an e-commerce app, we might have a cart object that exposes an addProduct function and a removeProduct function. We could then invoke these functions with cart.addProduct() and cart.removeProduct().

If you come from a Class-centric, object oriented, programming language like Java or C#, this probably feels quite natural.

If you’re new to programming — now that you’ve seen a statement like cart.addProduct(). I suspect the idea of grouping together functions under a single object is looking pretty good.

So how would we create this nice little cart object? Your first instinct with modern JavaScript might be to use a class. Something like:

// ShoppingCart.js

export default class ShoppingCart {
  constructor({db}) {
    this.db = db
  }
  
  addProduct (product) {
    this.db.push(product)
  }
  
  empty () {
    this.db = []
  }

  get products () {
    return Object
      .freeze([...this.db])
  }

  removeProduct (id) {
    // remove a product 
  }

  // other methods

}

// someOtherModule.js

const db = [] 
const cart = new ShoppingCart({db})
cart.addProduct({ 
  name: 'foo', 
  price: 9.99
})

Note: I’m using an Array for the db parameter for simplicity’s sake. In real code this would be something like a Model or Repo that interacts with an actual database.

Unfortunately — even though this looks nice — classes in JavaScript behave quite differently from what you might expect.

JavaScript Classes will bite you if you’re not careful.

For example, objects created using the new keyword are mutable. So, you can actually re-assign a method:

const db = []
const cart = new ShoppingCart({db})

cart.addProduct = () => 'nope!' 
// No Error on the line above!

cart.addProduct({ 
  name: 'foo', 
  price: 9.99
}) // output: "nope!" FTW?

Even worse, objects created using the new keyword inherit the prototype of the class that was used to create them. So, changes to a class’ prototype affect all objects created from that class — even if a change is made after the object was created!

Look at this:

const cart = new ShoppingCart({db: []})
const other = new ShoppingCart({db: []})

ShoppingCart.prototype
  .addProduct = () => ‘nope!’
// No Error on the line above!

cart.addProduct({ 
  name: 'foo', 
  price: 9.99
}) // output: "nope!"

other.addProduct({ 
  name: 'bar', 
  price: 8.88
}) // output: "nope!"

Then there's the fact that this In JavaScript is dynamically bound. So, if we pass around the methods of our cart object, we can lose the reference to this. That’s very counter-intuitive and it can get us into a lot of trouble.

A common trap is assigning an instance method to an event handler.

Consider our cart.empty method.

empty () {
    this.db = []
  }

If we assign this method directly to the click event of a button on our web page…

<button id="empty">
  Empty cart
</button>

---

document
  .querySelector('#empty')
  .addEventListener(
    'click', 
    cart.empty
  )

… when users click the empty button, their cart will remain full.

It fails silently because this will now refer to the button instead of the cart. So, our cart.empty method ends up assigning a new property to our button called db and setting that property to [] instead of affecting the cart object’s db.

This is the kind of bug that will drive you crazy because there is no error in the console and your common sense will tell you that it should work, but it doesn’t.

To make it work we have to do:

document
  .querySelector("#empty")
  .addEventListener(
    "click", 
    () => cart.empty()
  )

Or:

document
  .querySelector("#empty")
  .addEventListener(
    "click", 
    cart.empty.bind(cart)
  )

I think Mattias Petter Johansson said it best:

“new and this [in JavaScript] are some kind of unintuitive, weird, cloud rainbow trap.”

Ice Factory to the rescue

As I said earlier, an Ice Factory is just a function that creates and returns a frozen object. With an Ice Factory our shopping cart example looks like this:

// makeShoppingCart.js

export default function makeShoppingCart({
  db
}) {
  return Object.freeze({
    addProduct,
    empty,
    getProducts,
    removeProduct,
    // others
  })

  function addProduct (product) {
    db.push(product)
  }
  
  function empty () {
    db = []
  }

  function getProducts () {
    return Object
      .freeze([...db])
  }

  function removeProduct (id) {
    // remove a product
  }

  // other functions
}

// someOtherModule.js

const db = []
const cart = makeShoppingCart({ db })
cart.addProduct({ 
  name: 'foo', 
  price: 9.99
})

Notice our “weird, cloud rainbow traps” are gone:

• We no longer need new.
  We just invoke a plain old JavaScript function to create our cart object.
• We no longer need this.
  We can access the db object directly from our member functions.
• Our cart object is completely immutable.
  Object.freeze() freezes the cart object so that new properties can’t be added to it, existing properties can’t be removed or changed, and the prototype can’t be changed either. Just remember that Object.freeze() is shallow, so if the object we return contains an array or another object we must make sure to Object.freeze() them as well. Also, if you’re using a frozen object outside of an ES Module, you need to be in strict mode to make sure that re-assignments cause an error rather than just failing silently.

A little privacy please

Another advantage of Ice Factories is that they can have private members. For example:

function makeThing(spec) {
  const secret = 'shhh!'

  return Object.freeze({
    doStuff
  })

  function doStuff () {
    // We can use both spec
    // and secret in here 
  }
}

// secret is not accessible out here

const thing = makeThing()
thing.secret // undefined

This is made possible because of Closures in JavaScript, which you can read more about on MDN.

A little acknowledgement please

Although Factory Functions have been around JavaScript forever, the Ice Factory pattern was heavily inspired by some code that Douglas Crockford showed in this video.

Here’s Crockford demonstrating object creation with a function he calls “constructor”:

My Ice Factory version of the Crockford example above would look like this:

function makeSomething({ member }) {
  const { other } = makeSomethingElse() 
  
  return Object.freeze({ 
    other,
    method
  }) 

  function method () {
    // code that uses "member"
  }
}

I took advantage of function hoisting to put my return statement near the top, so that readers would have a nice little summary of what’s going on before diving into the details.

I also used destructuring on the spec parameter. And I renamed the pattern to “Ice Factory” so that it’s more memorable and less easily confused with the constructor function from a JavaScript class. But it’s basically the same thing.

So, credit where credit is due, thank you Mr. Crockford.

Note: It’s probably worth mentioning that Crockford considers function “hoisting” a “bad part” of JavaScript and would likely consider my version heresy. I discussed my feelings on this in a previous article and more specifically, this comment.

What about inheritance?

If we tick along building out our little e-commerce app, we might soon realize that the concept of adding and removing products keeps cropping up again and again all over the place.

Along with our Shopping Cart, we probably have a Catalog object and an Order object. And all of these probably expose some version of `addProduct` and `removeProduct`.

We know that duplication is bad, so we’ll eventually be tempted to create something like a Product List object that our cart, catalog, and order can all inherit from.

But rather than extending our objects by inheriting a Product List, we can instead adopt the timeless principle offered in one of the most influential programming books ever written:

“Favor object composition over class inheritance.”
– Design Patterns: Elements of Reusable Object-Oriented Software.

In fact, the authors of that book — colloquially known as “The Gang of Four” — go on to say:

“…our experience is that designers overuse inheritance as a reuse technique, and designs are often made more reusable (and simpler) by depending more on object composition.”

So, here’s our product list:

function makeProductList({ productDb }) {
  return Object.freeze({
    addProduct,
    empty,
    getProducts,
    removeProduct,
    // others
  )}
 
  // definitions for 
  // addProduct, etc…
}

And here’s our shopping cart:

function makeShoppingCart(productList) {
  return Object.freeze({
    items: productList,
    someCartSpecificMethod,
    // …
)}

function someCartSpecificMethod () {
  // code 
  }
}

And now we can just inject our Product List into our Shopping Cart, like this:

const productDb = []
const productList = makeProductList({ productDb })

const cart = makeShoppingCart(productList)

And use the Product List via the `items` property. Like:

cart.items.addProduct()

It may be tempting to subsume the entire Product List by incorporating its methods directly into the shopping cart object, like so:

function makeShoppingCart({ 
  addProduct,
  empty,
  getProducts,
  removeProduct,
  …others
}) {
  return Object.freeze({
    addProduct,
    empty,
    getProducts,
    removeProduct,
    someOtherMethod,
    …others
)}

function someOtherMethod () {
  // code 
  }
}

In fact, in an earlier version of this article, I did just that. But then it was pointed out to me that this is a bit dangerous (as explained here). So, we’re better off sticking with proper object composition.

Awesome. I’m Sold!

Whenever we’re learning something new, especially something as complex as software architecture and design, we tend to want hard and fast rules. We want to hear thing like “always do this” and “ never do that.”

The longer I spend working with this stuff, the more I realize that there’s no such thing as always and never. It’s about choices and trade-offs.

Making objects with an Ice Factory is slower and takes up more memory than using a class.

In the types of use case I’ve described, this won’t matter. Even though they are slower than classes, Ice Factories are still quite fast.

If you find yourself needing to create hundreds of thousands of objects in one shot, or if you’re in a situation where memory and processing power is at an extreme premium you might need a class instead.

Just remember, profile your app first and don’t prematurely optimize. Most of the time, object creation is not going to be the bottleneck.

Despite my earlier rant, Classes are not always terrible. You shouldn’t throw out a framework or library just because it uses classes. In fact, Dan Abramov wrote pretty eloquently about this in his article, How to use Classes and Sleep at Night.

Finally, I need to acknowledge that I’ve made a bunch of opinionated style choices in the code samples I’ve presented to you:

• I use function statements instead of function expressions.
• I put my return statement near the top (this is made possible by my use of function statements, see above).
• I name my factory function, makeX instead of createX or buildX or something else.
• My factory function takes a single, destructured, parameter object.
• I don’t use semi-colons (Crockford would also NOT approve of that)
• and so on…

You may make different style choices, and that’s okay! The style is not the pattern.

The Ice Factory pattern is just: use a function to create and return a frozen object. Exactly how you write that function is up to you.

If you’ve found this article useful, please smash that applause icon a bunch of times to help spread the word. And if you want to learn more stuff like this, please sign up for my Dev Mastery newsletter below. Thanks!

UPDATE 2019: Here’s a video where I use this pattern, a lot!

Elegant patterns in modern JavaScript: Ice Factory was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

I wrote my first few lines of JavaScript not long after the language was invented. If you told me at the time that I would one day be writing a series of articles about elegant patterns in JavaScript, I would have laughed you out of the room. I thought of JavaScript as a strange little language that barely even qualified as “real programming.”

Well, a lot has changed in the 20 years since then. I now see in JavaScript what Douglas Crockford saw when he wrote JavaScript: The Good Parts: “An outstanding, dynamic programming language … with enormous, expressive power.”

So, without further ado, here is a wonderful little pattern I’ve been using in my code lately. I hope you come to enjoy it as much as I have.

Please note: I’m pretty sure I did not invent any of this. Chances are I came across it in other people’s code and eventually adopted it myself.

Receive an object, return an object (RORO).

Most of my functions now accept a single parameter of type object and many of them return or resolve to a value of type object as well.

Thanks in part to the destructuring feature introduced in ES2015, I’ve found this to be a powerful pattern. I’ve even given it the silly name, “RORO” because… branding? ¯\_(ツ)_/¯

Note: Destructuring is one of my favorite features of modern JavaScript. We’re going to be taking advantage of it quite a bit throughout this article, so if you’re not familiar with it, here’s a quick video to get you up to speed.

Here are some reasons why you’ll love this pattern:

• Named parameters
• Cleaner default parameters
• Richer return values
• Easy function composition

Let’s look at each one.

Named Parameters

Suppose we have a function that returns a list of Users in a given Role and suppose we need to provide an option for including each User’s Contact Info and another option for including Inactive Users, traditionally we might write:

function findUsersByRole (
  role, 
  withContactInfo, 
  includeInactive
) {...}

A call to this function might then look like:

findUsersByRole(
  'admin', 
  true, 
  true
)

Notice how ambiguous those last two parameters are. What does “true, true” refer to?

What happens if our app almost never needs Contact Info but almost always needs Inactive Users? We have to contend with that middle parameter all the time, even though it’s not really relevant (more on that later).

In short, this traditional approach leaves us with potentially ambiguous, noisy code that’s harder to understand and trickier to write.

Let’s see what happens when we receive a single object instead:

function findUsersByRole ({
  role,
  withContactInfo, 
  includeInactive
}) {...}

Notice our function looks almost identical except that we’ve put braces around our parameters. This indicates that instead of receiving three distinct parameters, our function now expects a single object with properties named role, withContactInfo, and includeInactive.

This works because of a JavaScript feature introduced in ES2015 called Destructuring.

Now we can call our function like this:

findUsersByRole({
  role: 'admin', 
  withContactInfo: true, 
  includeInactive: true
})

This is far less ambiguous and a lot easier to read and understand. Plus, omitting or re-ordering our parameters is no longer an issue since they are now the named properties of an object.

For example, this works:

findUsersByRole({
  withContactInfo: true,
  role: 'admin', 
  includeInactive: true
})

And so does this:

findUsersByRole({
  role: 'admin', 
  includeInactive: true
})

This also makes it possible to add new parameters without breaking old code.

One important note here is that if we want all the parameters to be optional, in other words, if the following is a valid call…

findUsersByRole()

… we need to set a default value for our parameter object, like so:

function findUsersByRole ({
  role,
  withContactInfo, 
  includeInactive
} = {}) {...}

An added benefit of using destructuring for our parameter object is that it promotes immutability. When we destructure the object on its way into our function we assign the object’s properties to new variables. Changing the value of those variables will not alter the original object.

Consider the following:

const options = {
  role: 'Admin',
  includeInactive: true
}

findUsersByRole(options)

function findUsersByRole ({
  role,
  withContactInfo, 
  includeInactive
} = {}) {
  role = role.toLowerCase()
  console.log(role) // 'admin'
  ...
}

console.log(options.role) // 'Admin'

Even though we change the value of role the value of options.role remains unchanged.

Edit: It’s worth noting that destructuring makes a shallow copy so if any of the properties of our parameter object are of a complex type (e.g. array or object) changing them would indeed affect the original.

(Hat tip to Yuri Homyakov for pointing this out)

So far, so good, yeah?

Cleaner Default Parameters

With ES2015 JavaScript functions gained the ability to define default parameters. In fact, we recently used a default parameter when we added ={} to the parameter object on our findUsersByRole function above.

With traditional default parameters, our findUsersByRole function might look like this.

function findUsersByRole (
  role, 
  withContactInfo = true, 
  includeInactive
) {...}

If we want to set includeInactive to true we have to explicitly pass undefined as the value for withContactInfo to preserve the default, like this:

findUsersByRole(
  'Admin', 
  undefined, 
  true
)

How hideous is that?

Compare it to using a parameter object like so:

function findUsersByRole ({
  role,
  withContactInfo = true, 
  includeInactive
} = {}) {...}

Now we can write…

findUsersByRole({
  role: ‘Admin’,
  includeInactive: true
})

… and our default value for withContactInfo is preserved.

BONUS: Required Parameters

How often have you written something like this?

function findUsersByRole ({
  role, 
  withContactInfo, 
  includeInactive
} = {}) {
  if (role == null) {  
    throw Error(...)
  }
  ...
}

Note: We use == (double equals) above to test for both null and undefined with a single statement.

What if I told you that you could use default parameters to validate required parameters instead?

First, we need to define a requiredParam() function that throws an Error.

Like this:

function requiredParam (param) {
  const requiredParamError = new Error(
   `Required parameter, "${param}" is missing.`
  )

  // preserve original stack trace
  if (typeof Error.captureStackTrace === ‘function’) {
    Error.captureStackTrace(
      requiredParamError, 
      requiredParam
    )
  }

  throw requiredParamError
}

I know, I know. requiredParam doesn’t RORO. That’s why I said many of my functions — not all.

Now, we can set an invocation of requiredParam as the default value for role, like so:

function findUsersByRole ({
  role = requiredParam('role'),
  withContactInfo, 
  includeInactive
} = {}) {...}

With the above code, if anyone calls findUsersByRole without supplying a role they will get an Error that says Required parameter, “role” is missing.

Technically, we can use this technique with regular default parameters as well; we don’t necessarily need an object. But this trick was too useful not to mention.

Richer Return Values

JavaScript functions can only return a single value. If that value is an object it can contain a lot more information.

Consider a function that saves a User to a database. When that function returns an object it can provide a lot of information to the caller.

For example, a common pattern is to “upsert” or “merge” data in a save function. Which means, we insert rows into a database table (if they do not already exist) or update them (if they do exist).

In such cases, it would be handy to know wether the operation performed by our Save function was an INSERT or an UPDATE. It would also be good to get an accurate representation of exactly what was stored in the database, and it would be good to know the status of the operation; did it succeed, is it pending as part of a larger transaction, did it timeout?

When returning an object, it’s easy to communicate all of this info at once.

Something like:

async saveUser({
  upsert = true,
  transaction,
  ...userInfo
}) {
  // save to the DB
  return {
    operation, // e.g 'INSERT'
    status, // e.g. 'Success'
    saved: userInfo
  }
}

Technically, the above returns a Promise that resolves to an object but you get the idea.

Easy Function Composition

“Function composition is the process of combining two or more functions to produce a new function. Composing functions together is like snapping together a series of pipes for our data to flow through.” — Eric Elliott

We can compose functions together using a pipe function that looks something like this:

function pipe(...fns) { 
  return param => fns.reduce(
    (result, fn) => fn(result), 
    param
  )
}

The above function takes a list of functions and returns a function that can apply the list from left to right, starting with a given parameter and then passing the result of each function in the list to the next function in the list.

Don’t worry if you’re confused, there’s an example below that should clear things up.

One limitation of this approach is that each function in the list must only receive a single parameter. Luckily, when we RORO that’s not a problem!

Here’s an example where we have a saveUser function that pipes a userInfo object through 3 separate functions that validate, normalize, and persist the user information in sequence.

function saveUser(userInfo) {
  return pipe(
    validate,
    normalize,
    persist
  )(userInfo)
}

We can use a rest parameter in our validate, normalize, and persist functions to destructure only the values that each function needs and still pass everything back to the caller.

Here’s a bit of code to give you the gist of it:

function validate({
  id,
  firstName,
  lastName,
  email = requiredParam(),
  username = requiredParam(),
  pass = requiredParam(),
  address,
  ...rest
}) {
  // do some validation
  return {
    id,
    firstName,
    lastName,
    email,
    username,
    pass,
    address,
    ...rest
  }
}

function normalize({
  email,
  username,
  ...rest
}) {
  // do some normalizing
  return {
    email,
    username,
    ...rest
  }
}

async function persist({
  upsert = true,
  ...info
}) {
  // save userInfo to the DB
  return {
    operation,
    status,
    saved: info
  }
}

To RO or not to RO, that is the question.

I said at the outset, most of my functions receive an object and many of them return an object too.

Like any pattern, RORO should be seen as just another tool in our tool box. We use it in places where it adds value by making a list of parameters more clear and flexible and by making a return value more expressive.

If you’re writing a function that will only ever need to receive a single parameter, then receiving an object is overkill. Likewise, if you’re writing a function that can communicate a clear and intuitive response to the caller by returning a simple value, there is no need to return an object.

An example where I almost never RORO is assertion functions. Suppose we have a function isPositiveInteger that checks wether or not a given parameter is a positive integer, such a function likely wouldn’t benefit from RORO at all.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my Dev Mastery newsletter below.

Elegant patterns in modern JavaScript: RORO was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

Long ago a wise old developer gave me a piece of advice that I didn’t fully appreciate until very recently.

We were in a code review looking at some feature that required the program to output a list of letters from A-Z (think of a list of contacts with a set of buttons that allow you to skip down to names starting with a certain letter — that kind of thing).

So, along came some young hot-shot. (OK — it was me.) I decided that rather than just hard-coding an array of all the letters, it would be easier to write a for loop that iterated from 65–90, then use the values to generate the letters from their char codes.

The JavaScript equivalent would be something like:

for (let i = 65; i <= 90; i++) {
  letters.push(String.fromCharCode(i))
}

The wise old developer looked at me and asked why I hadn’t just hard-coded the array. It wasn’t as if the alphabet was going to be different from one session to the next. So why bother calculating it every time?

I was aghast. “You can’t really expect me to hand type every single letter like some child. I am a professional software developer! I have algorithms and data structures, and a math co-processor for heaven’s sake!”

“Fine,” he said. “Then use them at design-time to generate the array for you, and then copy/paste it into the production code.”

And then he said this:

“Avoid doing at runtime what you can do at design time”

Now, let’s be honest. My little for-loop wasn’t about to bring the application to a grinding halt. And today’s machines would crunch through that code so fast, no one would even notice. But as a general principle, it’s sage advice.

Too often we write code that transforms rarely-changing data from one format to another on every request.

Think of all the round-trips to fetch a piece of content from a database that might change once or twice a year, format it, and forward it to the browser, needlessly slowing down our apps.

This is especially true for sites that are tied to a content management system.

This is why I think established players like Wordpress, Drupal, and the like will face a credible challenge in the years to come from static site generators like Gatsby, Hugo, or Jekyll paired with a smooth build process, headless CMS, cheap CDNs, and a fast continuous integration workflow.

This pattern has been dubbed JAMstack, which stands for “JavaScript, APIs and Markup stack.” And the results are quite impressive.

The wise old developer’s advice echoes in my ears: “Avoid doing at run-time what you can do at design time.” And as time has worn on, I’ve realized that this piece of advice has far-reaching implications. Not just for software development, but for life too.

Recently, I’ve been reading a great book called “Principles: Work and Life” by Ray Dalio. A central theme of the book is that there are far fewer types of problem than there are actual problems. So if you do the work ahead of time and figure out how you would approach a particular type of problem you’re likely to face, then when it does arrive, you’ll be far better equipped to deal with it.

In essence, you can make better decisions more quickly by sorting out your approach to different problem types at “design time”, when you’re calmly reflecting on life, instead of at “runtime”, when you’re faced with an actual problem in the moment and panicking.

Dalio implemented this technique by cataloging his approaches as a set of principles. He even went so far as to codify his decision-making process into a set of computer algorithms that he could test against vast amounts of historical data.

Given that he’s a multi-billionaire who runs a very successful investment company, I’d say it’s worked out.

In fact, Wall Street is starting to hire more computer programmers than stock traders. So if you had any doubts that you chose the right profession, there’s more proof that software is eating the world.

I shared my own advice and lessons-learned in a recent interview on the Developer On Fire podcast which you can listen to here.

Episode 299 | Bill Sourour - Paying It Forward

You can learn more about JAMstack at Jamstack.org

JAMstack | JavaScript, APIs, and Markup

There’s also a nice round-up of static site generators on the Netlify blog at:

Top Ten Static Site Generators of 2017 | Netlify

And here’s an article about a specific stack that I recently reviewed and recommended which uses a combination of Gatsby, Contentful, Netlify, and Algolia as an alternative to a traditional CMS for a documentation site:

Gatsby + Contentful + Netlify (and Algolia)

This post originally appeared in the Dev Mastery Newsletter which I send out regularly to thousands of developers all over the world. Sign up below to get more content like this sent straight to your inbox.

If you enjoyed reading this, please help spread the word by smashing that applause icon a bunch of times. Thanks in advance!

Don’t do it at runtime. Do it at design time. was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

Such software will:

• be transparent, honest, and accountable in all user communication;
• function exactly as described;
• seek explicit user consent prior to collecting any user information; including both user-provided information and information collected from a user’s device or through integration with other services;
• seek explicit user consent prior to sharing any and all user information;
• use clear and plain language when seeking user consent;
• describe in clear and plain language what user information is collected and how;
• describe in clear and plain language where, when, and how any user information will be used;
• make it easy for users to withdraw consent at any time;
• make any user-generated content available for download by the user who generated it, free of charge, any time, with no restrictions;
• clearly identify any advertising or sponsored content;
• provide a simple, easy-to-use, and easy-to-find mechanism for users to opt out of any advertising or marketing;
• completely delete any and all user information upon request by the user; and,
• clearly and explicitly disclose any and all potential conflicts of interest including both conflicts that may arise through commercial interests and conflicts that may arise through political affiliation.

Stop me if you’ve heard this one before…

“Good code is self-documenting.”

In 20+ years of writing code for a living, this is the one phrase I’ve heard the most.

It’s cliché.

And like many clichés, it has a kernel of truth to it. But this truth has been so abused that most people who utter the phrase have no idea what it really means.

Is it true? Yes.

Does it mean you should never comment your code? No.

In this article we’ll look at the good, the bad, and the ugly when it comes to commenting your code.

For starters, there are really two different types of code comments. I call them documentation comments and clarification comments.

Documentation Comments

Documentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it. If you are building a library or framework that other developers will use, you need some form of API documentation.

The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it.

Here’s an example of a documentation comment from a popular JavaScript library called Lodash.

If you compare these comments to their online documentation, you’ll see it’s an exact match.

If you write documentation comments you should ensure that they follow a consistent standard and that they are easily distinguishable from any inline clarification comments you may also want to add. Some popular and well supported standards and tools include JSDoc for JavaScript, DocFx for dotNet, and JavaDoc for Java.

The downside of these kinds of comments is that they can make your code very “noisy” and harder to read for anyone who is actively involved in maintaining it. The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code.

Clarification comments

Clarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code.

Often, a clarification comment is a code smell. It tells you that your code is too complex. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.”

Here’s an example of a bad — though very entertaining — clarification comment.

/* 
 * Replaces with spaces 
 * the braces in cases 
 * where braces in places 
 * cause stasis.
**/ 
$str = str_replace(array("\{","\}")," ",$str);

Rather than decorating a slightly confusing statement with a clever rhyme — in amphibrach dimeter, no less — the author would have been far better off spending time on a function that makes the code itself easier to read and understand. Maybe a function named, removeCurlyBraces called from another function named sanitizeInput?

Don’t get me wrong, there are times — especially when you are slogging through a crushing workload — where injecting a bit of humor can be good for the soul. But when you write a funny comment to make up for bad code, it actually makes people less likely to refactor and fix the code later.

Do you really want to be the one responsible for robbing all future coders of the joy of reading that clever little rhyme? Most coders would chuckle and move on, ignoring the code smell.

There are also times when you come across a comment that is redundant. If the code is already simple and obvious, there’s no need to add a comment.

Like, don’t do this nonsense:

/*
set the value of the age integer to 32
*/
int age = 32;

Still, there are times when no matter what you do to the code itself, a clarification comment is still warranted.

Usually this happens when you need to add some context to a non-intuitive solution.

Here’s a good example from Lodash:

function addSetEntry(set, value) {   
  /* 
   Don't return `set.add` because it's not chainable in IE 11.
  */  
  set.add(value);    
  return set;  
}

There are also times when — after a lot of thought and experimentation — it turns out that the seemingly naive solution to a problem is actually the best. In those scenarios it is almost inevitable that some other coder will come around thinking they are much smarter than you are and start messing with the code, only to discover that your way was the best way all along.

Sometimes that other coder is your future self.

In those cases, it’s best to save everyone the time and embarrassment and leave a comment.

The following mock-comment captures this scenario perfectly:

/**
Dear maintainer:
 
Once you are done trying to 'optimize' this routine,
and have realized what a terrible mistake that was,
please increment the following counter as a warning
to the next guy:
 
total_hours_wasted_here = 42
**/

Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

Here’s a simple example in JavaScript:

/* 
don't use the global isFinite() because it returns true for null values
*/
Number.isFinite(value)

The Ugly

So, we’ve looked at the good and the bad, but what about the ugly?

Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

Things like the seemingly harmless…

/*
This code sucks, you know it and I know it.  
Move on and call me an idiot later.
*/

…to the downright mean

/* 
Class used to workaround Richard being a f***ing idiot
*/

These things may seem funny or may help release a bit of frustration in the moment, but when they make it into production code they end up making the coder who wrote them and their employer look unprofessional and bitter.

Don't do this.

If you enjoyed this article, please smash the applause icon a bunch of times to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.

Putting comments in code: the good, the bad, and the ugly. was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

Tabs or spaces? Curly brace on the same line or a new line? 80 character width or 120?

Coders love to argue about this kind of stuff. The tabs vs. spaces debate even made it into a famous episode of the HBO show Silicon Valley.

Well in this article, I will finally give you the definitive answers you seek.

Early in my career, I engaged in all kinds of holy wars. I would read some article about why a particular convention was correct, while another was totally wrong. I would get right up there on my high and mighty horse and proclaim to anyone who would listen that they were wrong and I was right.

It took me years to find the right answers but I’ve finally done it and it turns out the answer is…

These things don’t matter.

Consistency matters. Readability matters. Arguing and stressing about one convention over another matters not.

Over the past 20+ years, I’ve followed every imaginable trend. I’ve followed the different conventions of different languages. None of it has impacted my bug count or made my code any more efficient.

Don’t get me wrong, clean-looking, well-formatted code will be easier to change and maintain over time, and that’s a good thing.

There’s also nothing wrong with wanting your code to look beautiful. But too often, this is used to justify what essentially boils down to procrastination.

We procrastinate like this because coding is hard. Things can get complicated in a hurry and we — especially those of us who may be new to this level of complexity — can become intimidated by this complexity and grow insecure about our ability to tame it.

It’s much safer to argue over trivial things. Our perceived incompetence is less likely to be exposed that way.

The phenomena of debating trivialities to avoid hard problems is so common that there are a number of popular theories that describe it.

One of the most popular is Parkinson’s Law of Triviality which states that members of an organization give disproportionate weight to trivial issues.

In illustrating this law, Parkinson used the fictional example of a committee whose job it was to approve plans for a new nuclear plant, but who spent the majority of their time arguing over what materials to use for the staff bike shed. They neglected the proposed design of the plant itself, which was a far more important but also far more complex issue.

Because of the reference to a bike shed in this canonical example, Danish developer, Poul-Henning Kamp later coined the term “bike shed effect” or simply “bike shedding” to describe it.

If you work in software development — and especially if you hang out with other coders on social media — you’re likely to come across some form of bike-shedding almost daily.

If you find yourself getting into an unusually heated debate with your fellow coders, online or in-person, it’s probably also worth remembering Sayre’s Law…

“In any dispute the intensity of feeling is inversely proportional to the value of the issues at stake.”

As a consultant, I bounce from client to client, and each one has their own rules and conventions. I decided long ago that the only way for me to succeed was to let go of the trivialities and focus on the hard problems. When it comes to coding standards, I take what I get and I don’t get upset.

If you happen to find yourself in a position to pick your own style guide, I recommend that you ask yourself these two simple questions:

1. Is there tooling that will automatically apply the style rules to my code with little to no intervention from me?
2. Are the tools and underlying styles actively maintained and/or used by reputable organizations?

If you can answer “yes” to both of those questions, then you’re good to go. Simple as that.

Here are some options that fit the bill for some of today’s more popular web languages:

DotNet Code Formatter

Java: Google-Java-Format

Javascript Standard Style (N.B. this is a product name, not an actual, official JavaScript standard)

PHP Coding Standards Fixer

Python: Google’s YAPF

Ruby: Rubocop

If you enjoyed this article, please smash the clap icon at the bottom of this post repeatedly to help spread the word. And if you want to read more stuff like this, please sign up for my weekly Dev Mastery newsletter below.

The 100% Correct Coding Style Guide was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

Have you ever shipped a system completely free of technical debt? An application where no corners were cut and no compromises were made in service of deadline or budget? Small personal projects aside, over a 20+ year career, I have never seen such an application in a professional setting.

Author’s Note: This post is an excerpt from my weekly Dev Mastery newsletter. It was originally sent to Dev Mastery subscribers on December 8, 2016.

Check out this article from Tech Crunch about strategically planning your technical debt so that it can be managed and leveraged for maximum benefit.

How to make debt pay

The article makes some good points, but the author is clearly from a software product company background. There’s no question that it’s hard to convince a product manager to invest in a specific project dedicated to resolving technical debt, especially when that investment won’t result in any new features that the average customer might immediately notice. But at least at a software company there is some vague understanding of the business risk of technical debt. This understanding is much harder to find at agencies, consultancies, and in large enterprises.

If you’re not in a software company, it’s almost impossible to get anyone to approve some specific future project aimed specifically at eliminating technical debt. You have to pad your estimates for fixes or new features so that you can go back and clean a bit of your mess. And you have to be extremely careful about the kind of messes you make to begin with.

Speaking of cleaning messes, refactoring is an important skill for any developer. I’ve written about my approach to this before in…

How to conquer legacy code

Martin Fowler also maintains a good listing of common refactoring techniques that I often use as a reference…

catalog

The five I use the most are:

• Replace an exception with a test
• Replace assumptions with assertions
• Decompose a conditional
• Consolidate multiple conditional expressions
• Replace a constructor with a factory method

The post you just read was originally sent to Dev Mastery newsletter subscribers on December 8, 2016. I send out stuff like this every week. Sign up below to get in on the action.

Technical Debt was originally published in Dev Mastery on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’ve shared some pretty awesome links and resources through the Dev Mastery newsletter this year. Here are my top 5 favourites.

#5 — My Dog Taught Me to Code by Dave Thomas

Here is a video where the inimitable “Pragmatic Dave” Thomas shouts at you for almost an hour with really amazing advice that will help you improve your code. If you’re impatient, just skip to 4:52

#4 — Turning the Database Inside Out

Martin Klepmann makes the following provocative statement and provides a fascinating alternative model for Databases whose time I think has come.

“Databases are global, shared, mutable state. That’s the way it has been since the 1960s, and no amount of NoSQL has changed that. However, most self-respecting developers have got rid of mutable global variables in their code long ago. So why do we tolerate databases as they are?” — Martin Klepmann

If you’d rather read than watch, click here for the transcript.

#3 — Algorithm Visualizer by Jason Park

This amazing little web app let’s you play with some of the most common programming algorithms in JavaScript. Very cool.

#2 — Mastering Programming by Kent Beck

Kent Beck shares all the “ways effective programmers get the most out of their precious 3e9 seconds on the planet.”

“The journeyman learns to solve bigger problems by solving more problems at once. The master learns to solve even bigger problems than that by solving fewer problems at once.” — Kent Beck

#1 — The Future of Programming by Bob Martin

In this highly engaging and massively important talk, programming legend “Uncle Bob” Martin lays out the history of our profession and talks about what’s next. This is the talk that inspired me to share my story about the code I’m still ashamed of. It’s definitely worth your time.

On April 30, 2016 I sent out my first newsletter to 22 enthusiastic developers. Nine months later, my last newsletter of 2016 is going out to over 12,800 developers all around the world.

Use the form below to join them and get great stuff like this in your inbox every week.

Top 5 Developer Links of 2016 was originally published in Dev Mastery on Medium, where people are continuing the conversation by highlighting and responding to this story.

Have you heard of serverless architecture? Have you experimented with it? I have and I’m a big fan.

Serverless architecture lets you concentrate on code and not have to worry about anything else. Your logic just runs in this ephemeral, stateless container that comes and goes on demand. All the big cloud companies now support this; Amazon has AWS Lambda, Azure has Azure Functions, and Google has Google Cloud Functions.

Author’s Note: This post is an excerpt from my weekly Dev Mastery newsletter. It was originally sent to Dev Mastery subscribers on December 1, 2016.

One of the most thorough and balanced articles on the subject comes from Mike Roberts on Martin Fowler’s blog. Link below…

Serverless Architectures

Personally, I’ve experimented with a setup that includes Amazon S3 as a static host for the front end, and then AWS Lambda combined with API Gateway to handle the back end. When the budget is tight and you’re not dealing with critical security and privacy concerns, I’ve found this to be an excellent option.

I was an early adopter so I had to figure things out for myself using the documentation provided by AWS. Since then, the AWS blog has posted an article that describes how to do something very similar to what I set up for my client. It’s a good practical walk-through.

Microservices without the Servers

There’s also a product called Serverless that I have played with and seems to be maturing nicely. It abstracts away some of the configuration and setup steps when working with the AWS stack. I didn’t end up using it on client work because it was still in very early beta. But if you just want to quickly try out serverless architecture, it’s worth playing with. It’s free and pretty easy to use.

I haven’t tried Microsoft or Google’s offering yet, so I can’t speak to them. If you’ve had experience or know of good resources, let me know.

The last thing I’ll leave you with is a fun little distraction from the New York Times website that has nothing to do with serverless architecture. It’s a neat little game where you try to beat Usain Bolt’s reaction time (I like it best on mobile). If you’re new to web development and are looking for an interesting little learning project, try building a clone of this game. It will teach you about timers and the Audio API. It’s also a great time waster. My best score was 0.126.

Can You Beat Usain Bolt Out of the Blocks?

The post you just read was originally sent to Dev Mastery newsletter subscribers on December 1, 2016. I send out stuff like this every week. Sign up below to get in on the action.

I hate servers was originally published in Dev Mastery on Medium, where people are continuing the conversation by highlighting and responding to this story.

I have to make an embarrassing confession…

Many years ago (around 2002) I built a website in PHP. It was for a — now defunct — theatre company and included some basic functionality like a calendar and some lightweight content management features in a custom admin module I built. It was a small side project that I took on, in part, to learn PHP.

I came away from that experience thinking PHP was a steaming pile of garbage and I would tell anyone that would listen to me how terrible I thought PHP was. Here’s the embarrassing part; despite trashing PHP up and down, some of the websites and tools I use the most are PHP-based. This includes Wikipedia and Facebook. It also includes Wordpress, which is my number 1 recommendation when people ask me how they can create a website quickly with zero skills and almost no budget.

Author’s Note: This post is an excerpt from my weekly Dev Mastery newsletter. It was originally sent to Dev Mastery subscribers on October 19, 2016.

Now I’ve come to find out that Slack — another tool I use every day — is built with PHP. A slack engineer by the name of Keith Adams published a story on Medium that I think is worth a serious look. Link below…

Taking PHP Seriously

On a less embarrassing and more humbling note. I was honoured recently to be included in a list of Free Code Camp co-founder, Quincy Larson’s favourite stories of the year. I can’t say enough good about Quincy and his team and all the amazing things they are doing for burgeoning developers and for non-profits. Not to mention the stellar quality of their Medium publication.

I always look forward to reading their latest posts. Here are some of my recent favourites…

• What I learned from reviewing 50 portfolios on Reddit in 3 crazy days.
• JavaScript Fatigue Fatigue
• What does it mean when code is “easy to reason about”?

The post you just read was originally sent to Dev Mastery newsletter subscribers on October 19, 2016. I send out stuff like this every week. Sign up below to get in on the action.

OMG PHP WTF?! was originally published in Dev Mastery on Medium, where people are continuing the conversation by highlighting and responding to this story.