DEV Community: Karen White

Why Clean Code is Empathetic Code

Karen White — Wed, 17 Apr 2019 19:51:15 +0000

Originally published on the BigCommerce Developer Blog.

The idea for this post started over a beer.

I was catching up with Dan Murrell, Software Engineering Team Lead at BigCommerce, at a Friday happy hour when the conversation turned to a recent project Dan was working on. He told me how he had gotten well into development on a project, only to turn around and start over. He had realized that the code had become indecipherable to anyone but himself, and because of that, a course correction was needed. Not just because he didn’t feel like the quality met his standards, but also for the sake of any future engineers that were assigned to the project. He was currently in the process of reworking the project, organizing the code according to a set of guidelines designed to make it easy for other developers understand what the code was doing with minimal ramp up time.

This idea interested me, because it’s something that developers find themselves on both sides of. At different times, we might be the one who inherits a spaghetti code base — or, whether we want to admit it or not — the one creating it. Dan pointed out that over its lifetime, a project changes hands many times. And each owner has the opportunity to leave things better than they found them, or to create a giant mess that makes future developers curse their name.

I wanted to find out more about how Dan thinks about writing clean and readable code, so I met up with him again (no beer this time) to dig deeper into what it means to write code with empathy for future programmers.

A Life of Its Own

The first thing to understand is that most software has a life far beyond the original developer who created it.

“The reality is, if you’re doing any kind of software for a company, it’s going to almost certainly last far longer than you expected,” Dan says. But knowing that your code will live on and be passed to multiple owners changes your mindset about the code you write. “Your tendency is to make the code that you’re writing personal, and you put all your experience into it. But you’re not going to be the only person who ever works on this thing.”

No matter where you work writing software, it’s rare that you have the luxury of designing a solution from the start. Much more often, you’re working with a code base that you’ve inherited: either a legacy code base within your own company or a client whose website has passed through the hands of multiple developers before you. Being on the receiving end of a train wreck of a code base gives you first hand exposure to the consequences of ignoring clean code best practices.

Dan recalls, “I worked at an agency for five years, and my first project that I worked on was one that had started from scratch at the company, but the original developer had left. He hadn’t been using the greatest practices and then the project passed through three more developers before it came to me. We started adding new feature requests to it, and we had to understand what this thing does, because now we have to add new features that work with what’s already there. And inevitably, we had to rewrite a lot of code, because maybe it was out of date, or didn’t work, or it never worked in the first place. Probably the first year that I was at that company, it was really just orienting myself in this massive code base.”

Dan spent the next half year refactoring as he added the new features that were needed. And as the code base was cleaned up, new features that had once seemed impossible to build suddenly seemed straightforward.

“I had to take a step back and really consider what had happened. The refactoring work we did made that feature now possible. It wasn’t that it was easy to do — it was only easy to do after all the work we put into it.”

Why Good Developers Write Bad Code

If we assume that developers mean well, why is there so much illegible code out there? Are there just that many…bad developers?

Not at all. The truth is there are a number of factors working against even the most experienced developer. You might be under a tight deadline or building out a proof of concept — that later becomes a permanent solution. And in those cases, writing the most elegant and well-organized code possible might take a back seat to just making it work and getting the project out the door.

Plus, the idea that you’ll clean up a project later is often wishful thinking.

“Even an experienced developer has said 1000 times that they will get back to it, but you never get back to it. Sometimes you do, but more often you won’t. So taking care of things on the front end is the important consideration. Once you have self awareness of the amount of time that’s available to work on a thing, or the fact that you’re not going to be always the one working on the thing, you can make better decisions around how you structure your code,” Dan says.

Cleaning Up Your Act

We can all agree that it’s better to write legible code the first time around than waiting for a future refactor that may never come. But what do we actually mean when we say legible code — and how do you get there? Next, Dan shares a few tips for writing code that will make your project’s future owner thank you.

1. Practice.

Dan recommends building clean coding skills through bite-sized trainings. “There are practices that you can do, little exercises called Code Katas, that present you a simple problem. It’s something you can do on a lunch break or in 15 minutes, and it gives you a chance to work through a very short, brief problem in a way that you can practice clean code development.”

Consider it like building a muscle. These practice sessions can help you cultivate the ability to distill your code to its simplest form, and when best practices become second nature, it’s easier to maintain them.

2. Extract, extract, extract.

One of the biggest wins for code readability is extracting code out into single-use functions. Dan gives an example:

“Let’s say you write a 20 line function that does four different things. You can extract those four different things into their own separate functions. And when you do that, you’ve accomplished two things: you’ve isolated the individual things into their own containers and you’ve simplified the structure.”

Multi-purpose functions will always carry more of a cognitive load because the developer trying to decipher the code has to work out that the code is doing four different things. When you extract that out into separate functions, it becomes much easier to read what each piece of code is doing.

“Maybe your first function stores a setting on the server. And then maybe the second function you extracted uses that setting to make an API call. And then the next function does some kind of reaction based on the results, and so on,” Dan continues. “Those four functions basically read like a book that tells you what I’m doing.” Dan recommends extracting code out until each function has a single responsibility — and that’s it.

Once you extract everything out into single purpose functions, you can make your project even more readable by pushing those single use functions down to the bottom of your file. “Put them in private functions so they’re not being exposed to the global namespace, and then what you have as your global function is very simple, very clean: a function that calls those four other functions. That makes it very clean and linear at the top of the file, where somebody’s actually going to be reading, especially if the private function names are very descriptive,” Dan says.

“If you see a file that’s written that way, then you can almost certainly assume somebody has used clean code practices to extract, extract, extract and leave behind the very deliberate, very specific, easy-to-read things at the top.”

3. Use descriptive names.

Naming functions and variables descriptively is a practice that goes a long way toward making your code readable to others. “When you name things well, it self documents what you’re doing. Nobody wants to write documentation — and nobody wants to read it either. But if you if you name the functions and the variables descriptively, that makes it self documenting, and then you can take that whole documentation step out.”

At one point in time, it was best practice to be as concise as possible with naming conventions to conserve memory. But that’s no longer the case with today’s resource-rich computing.

“Back in the old days, you would use function names that were like two letters, or variable names like i and j and k. Nowadays, the compiler is going to compile code down, and storage is essentially free. So there’s really no reason to be brief with your function names and your variables when you don’t have to.”

Dan also prefers the self-documenting approach to comments in the code. “You do need to document any kind of information that somebody who’s going to consume a framework needs to know. If there’s a default to a Boolean, you should document what that’s going to be. But as far as multi line comments that explain just exactly what the code does — I never see that anymore.”

4. Leverage your tools

And when all else fails — automate it. Set yourself up for success by leaning on tools that take the guesswork out of clean code.

Dan says, “I use Xcode, and there are actually tools inside of Xcode that let you refactor things. It can extract methods out of a bigger block of code, put that put it in a new function, and figure out the inputs that need to go into it.”

Consistency is another factor that contributes to readable code, and linters are a great tool for enforcing style and formatting conventions. But linters are really only helpful if their usage is established early in the project. “Linters are one of the things you want to put in right at the beginning, because it’s going to flag everything that you’re doing that’s not following the standards that you set for that project. If you’re six months into a project and you’ve written 20,000 lines of code, you add a linter at that point…well just set aside your next month, because you’re just going to be fixing compliance issues,” Dan says.

If you’re inheriting an older project, a linter won’t help you much at that point. But if you’re fortunate enough to be starting a project from day 1, pulling in a linter can do a lot to make your code readable to the next developer assigned to the project.

Coding with Empathy

What really interested me about my conversation with Dan is the idea that this is not just an academic pursuit, writing clean code for clean code’s sake. There’s a human element to making your code simple and readable. Software is written by teams — not by lone geniuses. Coding with empathy means recognizing that other developers will contribute to your code down the line and making your code approachable to others.

And when you do that, you can begin to create work that goes beyond the individual and begins serving others. Everyone likes recognition, and it’s satisfying to solve a problem in a particularly clever way. But at the end of the day, it’s not just about you — it’s about the quality of the project and the success of all of the other team members, past, present, and future, who also have a stake.

Dan sums it up:

“Don’t write your code to be clever. Don’t try to impress anybody. If you use empathy driven development, where you’re thinking about the next person working on a thing, you’re going to make decisions keeping them in mind. And what it will do is keep your ego in check, and take your ego out of the equation.”

Conclusion

Most developers don’t set out to write code that makes sense only to them, but the reality is that there are factors that work against those good intentions. You might be building out a proof of concept or an MVP that you mean to come back and refine later — but later never comes. Or, you might start out as a project’s sole owner, only to move on or expand your team.

Once you recognize that software has a life far beyond its original creator, you can start to employ clean code practices by:

Training up with problem solving exercises
Extracting functions into single-purpose blocks
Naming functions and variables descriptively
Using built-in tools and linters to automate consistency

…and you’ll produce code that doesn’t make life difficult for future developers working on your project. That’s not just coding with empathy, that’s good karma.

Thanks to Dan Murrell for the insights and the conversation that sparked this post. You can find Dan on Twitter @danimal99 or tweet us @BigCommerceDevs. Cheers! 🍻

How to Test App Authentication Locally with ngrok

Karen White — Fri, 18 Jan 2019 22:41:58 +0000

Originally published on the BigCommerce Developer Blog, January 5, 2019

Developing locally makes it fast and easy to test changes as you work, but no network access has its disadvantages. You might run into situations where you need a publicly accessible URL while you’re still in the development phase. Maybe you want to show your work to a colleague or client, or you need a secure, publicly available callback URL to interact with a web service. You could go ahead and upload your app to a hosting platform like Heroku, but then every time you make an update, you’d have to push those changes to your host server…not great.

Luckily, there’s ngrok. Ngrok is a handy tool that creates a secure, publicly accessible tunnel URL to an application that’s running on localhost. You can share the tunnel URL so others can view your work, or you can create publicly accessible routes to do things like complete an Oauth handshake.

In this tutorial, we’ll build a super simple Node app for BigCommerce and demonstrate how you can use ngrok to retrieve an Oauth token from the BigCommerce auth service and install the app in your store, all while still working locally. Consider this your comprehensive guide to testing, running, and authenticating BigCommerce apps locally.

What Is ngrok?

Ngrok is a free program that exposes a process running on your localhost to the public internet. When you start up ngrok, you specify which port your local server is running on and ngrok creates a secure tunnel URL to make the local application publicly accessible. Visit the ngrok URL and you’ll see the same thing you see when visiting http://localhost:myport.

When you start ngrok, you’ll see a printout like this in your terminal:

Notice those two forwarding addresses? Ngrok provides both an https and an http version of the URL that points to localhost. Ngrok also provides a Web Interface dashboard that prints out details on any http traffic that’s going through your tunnel. This can be extremely useful during app development, especially when dealing with webhooks.

By default, ngrok generates a random subdomain every time you start it up. That’s fine for testing, but it can be a pain if you’re working on a project over a span of time and have to keep updating the URLs in your project every time you restart ngrok. If you sign up for a paid plan, ngrok allows you to designate a custom subdomain, so you’ll have the same URL every time.

Really, the best way to explain how ngrok works is to show you. Let’s download ngrok and spin up a quick app to run on localhost to demonstrate.

How To Set Up ngrok

Ready to get started? You can install ngrok using npm (my preferred method) or you can install manually.

Install with npm

Be sure you have Node.js installed on your computer. Run the following terminal command to confirm Node is installed and check your version:
node -v
Run npm install -g ngrok to install ngrok globally. You can now run ngrok commands from any directory.

Install manually

Head to https://ngrok.com/download and download the package that corresponds to your operating system.
Unzip the file somewhere easy to access, like the root folder.
You can either navigate to the folder where you unzipped ngrok to run it, or if you want to run ngrok from any location, you can move it to a directory which is in your $PATH, usually /usr/local/bin.

Start ngrok

Open a terminal window and navigate to the location where you unzipped ngrok. If you’ve installed ngrok globally or moved it to your $PATH, you can go ahead and run ngrok from any directory.
Run the following command to start ngrok and create a tunnel to localhost port 3000:
ngrok http 3000
Press Ctrl + C to stop ngrok.

Create an Express App

Express is a framework for creating skeleton Node.js apps. It’s a great way to quickly create the file structure for your app.

Install the express generator command line tool with the following terminal command:
npm install express-generator -g
Create the app. We’re specifying that the app should use the handlebars view engine and be created in a folder called myapp:
express — view=hbs myapp
Navigate into the myapp folder:
cd myapp
Install the dependencies:
npm install
Start the app with the following command:
npm start

Tunnel ngrok to localhost

Time to put the pieces together. We’ve installed ngrok and created a skeleton app using Express. Now, we’ll start the application and ngrok to see the tunnel URL in action.

Open a terminal window and navigate to your myapp directory. Run npm start to start the app. By default, Express generator apps start the server on localhost:3000. If you want to change the port, it’s defined in the app’s bin/www file on line 15, but we’ll leave it on port 3000 for now.
Open a browser window and navigate to http://localhost:3000. You should see the Express app home page:

Open a new terminal window (leave the first terminal window running) and start ngrok on port 3000:
ngrok http 3000
Copy the https forwarding URL from the terminal and paste it into a new browser tab. You should see the same Express app homepage that you saw on your localhost URL:

Hooray! This may not look like much yet, but we’ve already demonstrated a powerful feature of ngrok. You could email your ngrok forwarding URL to a friend, and they’d see the same Express app homepage (as long as you’ve got ngrok running in your terminal). That’s pretty cool, but next we’ll show how you can use ngrok to do even more. We’ll create a forwarding URL that will allow us to create publicly accessible routes within the app so we can complete the Oauth flow necessary to install the app in a BigCommerce store.

BigCommerce App Authentication

Before we move on, it helps to have a little background on BigCommerce app authentication, to illustrate why ngrok is needed to install an app that’s still hosted locally.

BigCommerce apps use Oauth to programmatically generate an API token against a store during installation. Once an app has received an API token for a store, the app can save the token in a database for reuse when calling the API.

The process to receive an Oauth token requires a little back and forth between BigCommerce and the app host. First, the app needs to request a temporary auth code from BigCommerce. When BigCommerce sends the temporary token, it sends along a couple of other pieces of information as well: the scopes that have been authorized for the API token and the hash, or identifier, for the store that’s installing the app.

Next, the app posts back a response containing a series of claims that let the BigCommerce auth service know it’s okay to return a real Oauth token. Those claims include the temporary auth token received previously from BigCommerce, the store hash, the scopes, and a Client Id and Client Secret that were provided during app registration. If everything checks out, the BigCommerce auth service sends back a permanent Oauth token and the app shows ‘Installed’ in the store control panel.

All of these network requests need to happen over publicly accessible URLs. When testing app installation and authentication, we either need to host the app on a server, or a platform like Heroku, or use a tool like ngrok to create tunnel URLs from localhost.

Register the App

To install an app in a BigCommerce store, you’ll need, not surprisingly….a store. Sign up for a free trial at https://www.bigcommerce.com/.

Then, sign up for a Dev Tools account at https://developer.bigcommerce.com/ by clicking Create Account in the top right corner. Be sure to use the same email address that you used to sign up for your trial store. Using the same email address links your trial store and your Dev Tools accounts, so any apps that you create in Dev Tools will be available for installation in the Draft Apps area of your store’s control panel.

Dev Tools is the workspace for creating BigCommerce apps. It’s where you go to register a new app and manage app listing details if you’re a vendor in the App Marketplace. For now, we’ll just do the minimum steps to register a new app and get a Client Id and Client Secret.

Log in to Dev Tools and click the orange Create an app button.
Enter a name for your app. This could be anything — My Test App, Node App, whatever you’d like.
Click Create App.
Click the Edit App icon on the app you created.
On Step 1, you can skip filling out the profile form. This just collects information that BigCommerce needs for developers who want to submit their app to the App Marketplace. It’s not required, but I do like to go ahead and upload an image to the App summary area at the bottom. The image will show on the card for your draft app in the control panel. Again, not required, but it does look nicer.
Skip Step 2: App Details and proceed to Step 3. App details are required only for developers who want to submit an app to the Marketplace.
On Step 3, fill in the Callback URL fields, replacing example.com with your https forwarding URL from ngrok. For example:
Auth: https://4022ffe4.ngrok.io/auth
Load: https://4022ffe4.ngrok.io/load
Uninstall: https://4022ffe4.ngrok.io/uninstall
Click Next until you reach Step 6, then click Update and Close.

Create Routes in Express

During app registration, we defined three callback URLs: Auth, Load, and Uninstall. These URLs tell BigCommerce: when someone installs, loads, or uninstalls my app, here’s where you should send the http request for that action. Next, we’ll create those routes in the Express app to handle the authorization, load, and uninstall requests from BigCommerce.

A route listens for an http request, a GET or a POST, to a particular path and then does something, like running a function or calling a response method, when the http request happens.

Create the Auth route:

Install the BigCommerce Node Client by running npm install node-bigcommerce in your myapp directory. This package was written by the developers at Conversio, and is used to authenticate with and call the BigCommerce API.
Create a new file in the routes directory called auth.js.
Paste the following into the file contents:

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');

const bigCommerce = new BigCommerce({
clientId: 'your Client Id from app registration',
secret: 'your Client Secret from app registration',
callback: 'https://your-ngrokURL/auth',
responseType: 'json'
});

router.get('/', (req, res, next) => {
bigCommerce.authorize(req.query)
.then(data => console.log(data))
.then(data => res.render('auth', { title: 'Authorized!' })
.catch(err));
});
module.exports = router;

Here, we’re requiring the Express router and BigCommerce Node Client at the top of the file and instantiating a new BigCommerce config object.

Take a look at the function below the BigCommerce config object. With router.get(‘/’, (req, res, next), we’re telling the router, when you receive a GET request to this path (this path is /auth, because we’re in the routes/auth.js file), call the authorize function from the Node Client dependency.

The authorize function returns a data object from BigCommerce containing the store hash, the user’s email address (to identify the user), and the Oauth token associated with the store. If we were to develop this app further, we’d want to save that information to a database for reuse.

Once we return the Oauth token, we call res.render to render a view called ‘auth’ that passes in the text “Authorized!”

Replace the values for your Client Id, your Client Secret, and your ngrok tunnel URL.
Create the ‘auth’ view by creating a new file in your Views folder called auth.hbs.
Paste the following into the file contents:
<h1>{{title}}</h1>

Create the Load route:

Create a new file in your Routes folder called load.js
Paste the following into the file contents:

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');
const bigCommerce = new BigCommerce({
secret: 'your Client Secret',
responseType: 'json'
});

router.get('/', (req, res, next) => {
try {
const data = bigCommerce.verify(req.query['signed_payload']);
console.log(data);
res.render('welcome', { title: 'Welcome!'});
} catch (err) {
next(err);
}
});

module.exports = router;

Replace the value for ‘secret’ with your Client Secret. Similar to the /auth route we created, we’re specifying a callback function to execute after a GET request to the /load route. We’re calling the verify function which validates that the request came from BigCommerce and identifies the store and user. When that’s successful, we console log the data object and render the view called ‘welcome.’
Create the ‘welcome’ view by creating a new file in your Views directory called welcome.hbs.
Paste the following into the file contents:
<h1>{{title}}</h1>

Create the Uninstall Route:

Create a new file in your Routes directory called uninstall.js
Paste the following into the file contents:

const express = require('express'),
router = express.Router(),
BigCommerce = require('node-bigcommerce');
const bigCommerce = new BigCommerce({
secret: 'Your Client Secret',
responseType: 'json'
});

router.get('/', (req, next) => {
try {
const data = bigCommerce.verify(req.query['signed_payload']);
console.log(data);
} catch (err) {
next(err);
}
});

module.exports = router;

Replace the value for ‘secret’ with your Client Secret. In the /uninstall callback, we’re using the verify function to decode the signed payload sent from BigCommerce and logging the payload identifying the user who uninstalled the app. We’re not rendering a view in this case, because any HTML sent back to BigCommerce wouldn’t be rendered by BigCommerce.

Load Router Modules in App.js

Before we can use the route modules we’ve created, we need to mount the router modules on a path in the main app file.

Add the following near the top of your app.js file:

var auth = require(‘./routes/auth’);
var load = require(‘./routes/load’);
var uninstall = require(‘./routes/uninstall’);

Locate these lines, near the middle of the app.js file:

app.use(‘/’, index);
app.use(‘/users’, users);

Beneath them, add:

app.use(‘/auth’, auth);
app.use(‘/load’, load);
app.use(‘/uninstall’, uninstall);

Install the App

Now that we have the app wired up to the appropriate route paths, it’s time to install the app in your store.

Start the Express app by running the npm start command in your myapp directory.
Open a second terminal window and start ngrok on port 3000:
ngrok http 3000

Be sure to update the ngrok URL in Dev Tools to match the ngrok URL in your current session.

Log in to your BigCommerce store and navigate to Apps>My Apps>My Draft Apps tab.
Click Learn More on your app card and then click Install. You should see your app’s Authorized! Message. The Authorized! view indicates that we’ve successfully received an Oauth token from BigCommerce.
Test the Load route by returning to the My Apps section in the control panel. Now that the app is installed, you’ll see two new buttons: Load and Uninstall. Click the Load button to render the Welcome view.
Now, click the Uninstall button. The app will be removed from the My Apps section. Check your terminal for the auth, load, and uninstall data objects that were logged to the console.

FAQ

I’ve installed ngrok. Why am I getting ‘command not found’ when I try to start it?

You’re likely not running ngrok from the working directory for the executable file. You can either move the file to your $PATH directory, or navigate to the directory containing the ngrok .exe file. For example, if you unzipped ngrok in your root directory, you can run it using:

cd ~

./ngrok http 3000

How can I use ngrok to test webhooks?

Webhooks allow you to listen for events that happen on a third party’s platform. For example, your app might want to receive a notification when a BigCommerce product’s inventory changes so your app can take an action of some kind.

When you register a webhook, you can provide an ngrok tunnel URL as the destination URL. When the webhook event happens, you’ll receive the webhook data object through your tunnel. You can display the details of the data object in your ngrok Web Interface dashboard and handle the event within your app.

For more details on testing webhooks with ngrok, see this tutorial on registering and testing webhooks.

Why do I get a 502 bad gateway error when I visit my ngrok tunnel URL?

Ngrok expects a web server to be running on localhost. If there isn’t a server running, you’ll see a 502 error accompanied by a message that ngrok failed to complete the tunnel connection. By default, Express generator apps start a server on port 3000, so you’ll just want to make sure you start your app before making requests to your ngrok URL.

Summary

In this tutorial, we installed ngrok and used it to tunnel the routes that we registered on our locally hosted app to publicly accessible callback URLs. Great job! You’re now well on your way to building and testing your apps locally — no need to deploy your changes to an app host while you’re still in the development phase.

Use this as a starting point to build out more complexity in your app: save your Oauth token to a database and use it to call the BigCommerce API or create view templates that provide a UI for your app users. Looking for Hello World apps in Python, PHP, or Ruby? Visit the BigCommerce Tools & Resources page for sample apps and API clients in other languages.

Let us know what you’re working on, ask us questions, send us your feedback! Comment below or tweet us @BigCommerceDevs