DEV Community: TJ Wright

Quickly Open a File in the Browser from WSL

TJ Wright — Sat, 17 Oct 2020 19:54:54 +0000

Mac users have this magic convenience of typing open index.html into their terminal to open a file from their current directory in the browser. Those of us on WSL aren't so lucky. If you're lucky, the open command will open a windows directory. Cool, I guess? But not exactly super helpful. The internet abounds with recommendations --- from trying xdg-open, configuring your www-browser defaults, and setting your PATH environments to some even more convoluted methods. But the question remains: what's the easiest way to open an HTML file in the browser from WSL?

The closest thing I've found is to use the Windows Subsystem for Linux's explorer.exe command. Assuming you've set your browser environment variable in bash, then typing something lile explorer.exe index.html should open the file index.html in your default browser. If that works, congrags! That's the simplest version of Mac's open command. Well, sort of...

Typing explorer.exe is still a little bit of a handful, and I'm lazy. I mean open is four characters, and explorer.exe is twelve. That's three times as many characters. No thanks!

Wouldn't it be nice if we could do something simpler? How about see index.html? Fortunately, we can leverage the ability to create aliases in bash to make this dream a reality. Just drop the following three lines directly into your terminal:



export BROWSER='/mnt/c/Windows/explorer.exe'
echo "alias see='explorer.exe'" >> ~/.bashrc
source ~/.bash_profile

You're done! No need to play around in your config files. 🙌 Next time you need to open that index.html file, all you need to do is type see index.html and watch the magic happen. And it's one fewer character than those Mac folks. Just imagine what you could do with that kind of time savings...

Save time debugging Rails by automatically displaying params directly inside your views

TJ Wright — Thu, 20 Aug 2020 17:13:43 +0000

Here's a fun and easy little trick. Let's throw a debug(params) into our view, and then we can see what our params are for every page! In Rails, this means seeing the controller/action for every page you visit as well as any dynamic content that was used for each view --- nifty!

1. Add the debug

First, let's head into our application.html.erb page and add it into our layout, in this case right under the footer:

<!DOCTYPE html>
<html>
  <head>
    <title><%= full_title(yield(:title)) %></title>
    <meta charset="utf-8">
    <%= render 'layouts/rails_default' %>
    <%= render 'layouts/shim' %>
  </head>
  <body>
    <%= render 'layouts/header' %>
    <div class="container">
    <%= yield %>
    <%= render 'layouts/footer' %>
    <%= debug(params) if Rails.env.development? %>
    </div>
  </body>
</html>

(While not absolutely necessary, our post-fix conditional if Rails.env.development? makes sure that if we were to accidentally push this guy into production we wouldn't see it!)

2. Add some style

The debug will be styled using .debug_dump class selector. We can use a mixin from Sass called box_sizing to make this extra pretty. Head into your app/assets/stylesheets/custom.css file and drop this in:

@import "bootstrap-sprockets";
@import "bootstrap";

$gray-medium-light: #eaeaea;

@mixin box_sizing {
  -moz-box-sizing:    border-box;
  -webkit-box-sizing: border-box;
  box-sizing:         border-box;
}

.debug_dump {
  clear: both;
  float: left;
  width: 100%;
  margin-top: 45px;
  @include box_sizing;
}

3. Results

Great! Now load up your rails server and check out your pages. You should see a beautiful little grey box with useful info about the page that is rendered; specifically, you'll see your page params in a pretty little YAML format!

Thanks go to Michael Hartl's excellent Learn Enough series for this tip!

Did MySpace Get You Interested in Coding?

TJ Wright — Fri, 08 May 2020 17:00:00 +0000

One thing that I keep seeing over and over again...
a generation of developers inspired by... MYSPACE.

If that's you, I want to hear about it!

Did you go to school for development, are you attending a boot camp, are you totally self-taught? What do you do now? What was your favorite MySpace memory? Share your story!

the face that launched a thousand coders

Updating to the New WSL 2: Is It Really 20x Faster? - A User's Installation Guide

TJ Wright — Fri, 08 May 2020 00:08:58 +0000

Windows has finally released WSL 2, and it's smooooooooth. Microsoft describes it as such: "WSL 2 is a major overhaul of the underlying architecture and uses virtualization technology and a Linux kernel to enable its new features."

If you're like me, you found the first iteration of WSL to be an absolute slog. Slow, unruly, resource-heavy, and sometimes just downright buggy. Fortunately, Windows has delivered us an update that fixes tons of these issues, with reported speed boosts of anywhere between 3-6x faster (when running git commands, setting up libraries, and more) to 13x-20x faster (miscellaneous filesystem commands, such as unzipping tar volumes). That's a performance boost that is way worth the upgrade! After installing, I can definitely confirm: WSL 2 is faaaaaaaast. Like, way faster. A bundle install in Rails takes only a few seconds, where on WSL 1 it could sometimes take actual minutes. If you're ready for that kind of upgrade, follow along with the steps below!

We're going to take a few steps here, so I wanted to give a roadmap of where we're headed. (Click here if you just want to jump to the TL;DR short version of this post!) WSL2 doesn't quite run out of the box yet; it requires a few features that WSL1 didn't use, specifically the "Virtual Machine Platform". First, we'll update our system, then we'll turn on VMP, and last we'll install the WSL2 kernel. From there, it's off to the races!

One word of warning before starting: there are a few (very few) changes in WSL2 that might impact your typical workflow. The biggest difference I've experienced is that running a server, e.g. rack or rails, will no longer use localhost. Since WSL2 runs inside a virtual machine, you'll be given a local IP address to use instead. The speed boosts make this small change absolutely WORTH it!

So, what are you waiting for? Let's get started!

Pro Tip: Before starting, install the new preview of the Windows Terminal. Use it to quickly switch and open multiple terminals across kernels, including command prompt, Bash, Powershell, and more.

Step One: Update Windows

1. Check your current version

Let's start by checking our version of Windows by heading to the start menu and opening the command prompt (just type command into the start menu). If you weren't aware, Windows has both a build number and a version number. Typing winver into the command prompt will give us a full breakdown of our current build and version.

Some older documentation from last year indicates that you'll need a build higher than 10.0.18917. Some newer documentation suggests build 19041. Rather than getting caught up in build numbers, we'll focus on the magic version number: 2004.

2. Update Windows through your settings

Go ahead and open your Windows settings to the "Updates and Security" page. If you see an "Update Now" button, go for it! You can force Windows to check for updates by clicking "Check for Updates." If you're like me, my automatic updates only scooted me to version 1903... I think I may have missed a few updates. Oops! Either way, go ahead and install any updates you need. I'll wait!

3. Join the Windows Insider Program

Okay, so you may not be on Magic Version 2004 yet. To jump ahead a few more versions, we'll have to join the Windows Insider Program. Head to that page, and click the blue box that says "BECOME AN INSIDER". You'll be prompted to sign in to your account, do so!

Next, head back to your "Updates and Security" menu. Click the "Windows Insider Program" on the bottom left side. Follow the instructions that pop up. It should ask you to "connect your account", and you should use the one you just chose on the "Become an Insider" webpage. Then it'll ask you to select an Insider track. Fortunately, WSL2 is available on both the Slow and Fast tracks. I selected Slow since it's a little more stable and has less frequent updates. From there, you'll be prompted for a few restarts. These took a very long time and made a lot of noises... in fact, I wrote this entire post while I waited! Bookmark this page and come back when you're done, or go ahead and open it on your phone. I'll be here when you get back.

Step Two: Turn on Virtual Machine Platform

The Virtual Machine Platform was, as far as anyone can tell, designed specifically for WSL2. While the feature has been available for a while now, you probably didn't have it turned on. In the past, WSL relied on Hyper-V. While that still may be true, the Virtual Machine Platform is the catalyst for WSL2's blazing speeds. At least, we think so. Quite honestly, it's hard to find much information about VMP online. It looks like it's part of a bigger program at Microsoft to support a wider array of virtualization options for users. If you know more about this, drop some knowledge in the comments section! Either way, it's the key here to getting WSL2. Let's turn it on now.

Head to your start menu, and type "windows features" and select "Turn Windows Features On/Off".
Find and select "Virtual Machine Platform." This should activate the VMP feature!

Reboot!

Not so bad, was it? Time to update our kernel.

Step Three: Update the WSL2 Kernel

Rejoice! This isthe easiest step so far. 🙌 Head to the Microsoft website to download the Linux kernel update. Once downloaded, run the update package. You'll be asked about giving admin permissions, select "yes" to approve, and the install will begin.

The cool part of WSL2 and the new kernel is that it's a real part of Windows. By that, I mean you should no longer have to jump through hoops to install updates! In your Windows settings, you've sometimes seen the 'Check for Updates' button that quickly updates applications related to your PC like drivers, Windows software like Defender, or other items en masse. Thankfully, Microsoft is now using this method to deliver updates to the Linux kernel in WSL!

Step Four: Update your Linux distros

Okay, back to the command prompt! Type wsl -l -v. This should give you an output with information about your Linux builds. I have Ubuntu and Kali installed in WSL. I don't use Kali too much at the moment, so I'm just going to update Ubuntu to version 2.

Let's change those version numbers! In the command prompt, type:

wsl --set-version Ubuntu 2

This will begin the process of converting Ubuntu over to WSL 2. It took mine quite a bit of time to do... like, a LOT of time. In fact, I was worried it wasn't working. I looked into it, and found a post about this on Reddit. A WSL developer responded and clarified that, essentially, the conversion from WSL 1 to WSL 2 requires Windows quite literally transferring your entire file system to a virtual system. So if you have a lot of things installed---frameworks, languages, utilities, etc---it can take a very long time. Mine finished in just under two hours, some reported even longer times. The good thing, however, is that when you're done, YOU'RE DONE!

Congratulations! You're now running the latest and greatest version of the Windows Subsystem for Linux: WSL 2! HAPPY CODING!

The TL;DR Version

Update Windows to at least version 2004. If you can't do it through Windows Update, you'll need to join the Insider Program on either the Slow or Fast track.
Turn on the Virtual Machine Platform in your Windows features.
Install the WSL2 kernel.
Update each distro from the command prompt. Type wsl -l -v to see the current distros, and wsl --set-version <Distro> 2 to convert them.

Looking for some more info? Click here to check out a full list of changes in WSL 2, as well as further documentation from Microsoft.

Installing the Heroku CLI on WSL

TJ Wright — Fri, 01 May 2020 03:23:29 +0000

Wait, wait, let me guess...

You're running WSL.

You're trying to install Heroku on the command line.

It's not working.

First, you tried downloading the installer, and that didn't work.

Then, you tried tossing sudo apt-get heroku into your bash terminal, and that didn't work.

And then you ended up here. (Or, more likely, searching way too long on StackOverflow.)

Never fear: the answer is right here.

Pop open that bash terminal, and toss in this line:

curl https://cli-assets.heroku.com/install.sh | sh

Then lean back and let the Heroku CLI install.

You're not done quite yet, though. Once it's installed, give heroku apps or heroku open a whirl and you should be prompted with an opportunity to log in.

Enter those credientials, and all of the magic of the Heroku CLI is yours.

One thing to note, you probably have to add an --app flag for whatever apps you're running a command against. While most of the Heroku documentation doesn't indicate that, you'll want to include -a your-app-name at the end of every command you run that's app-specific.

For example, the documentation for running migrations says to use heroku rake db:migrate. But you'll have to use heroku rake db:migrate -a your-app-name. Trying to see your error logs? Try heroku logs -a your-app-name instead of heroku logs. You can check out which commands require the -a or --app flag, and which don't on the giant list of Heroku CLI commands.

Looks like you're off to the races, my WSL compadre.

Want to know more about why curl works? Check out the ultimate guide to everything curl!

A Primer on Relational Databases for Beginners by a Beginner

TJ Wright — Fri, 01 May 2020 02:32:13 +0000

Today things like SQL, Oracle, MongoDB are all commonplace names in software engineering and web development. On the back-end, we expect a full-stack engineer to have a firm grasp on database management. So let's talk about what a database management system entails, starting from the very basics.

A database is a collection of related information stored in a manageable and accessible way. Years ago, we stored data on tapes. Super convenient, right? Not exactly. As tapes started to become unwieldy and technology outpaced the physical medium, more practical systems of data management evolved. The goal of a well-formed management system will reduce redundancy, maintain consistency, and support concurrent access. These systems provide security and support for transactions between users. They also support languages that allow us to create, add, alter, or delete data.

The core components of a database management system involve:

Data and metadata --- consisting of our information
Databases --- composed of software and hardware working together to give us a place for storage, retrieval, and interaction
Access languages --- comprised of tools to access and interact with the data stored in the databases

The architecture for database management systems, sometimes called database engines will differ in myriad ways. It could be decentralized or hierarchical; it could have graphic user interfaces; it could have multiple users, clients, or different languages, but the basic (i.e. minimum) requirements are always the same: (1) data, (2) databases, and (3) access languages. Let's talk about each of those pieces in turn.

Data

"Data is all around us." We tend to hear that a LOT these days. But what on earth is it, how do I store it, what do I do with it, what does anyone do with it? Let's talk about data.

Simply put: data is information. Every property or attribute of every moment in time can be summarized as a bit of data. Your longitude and latitude right now could be recorded as a piece of data --- in fact, it probably is. The ability to generate data has exploded thanks to our devices, which work constantly to produce data points, like location, orientaton, time, user. Toss in cameras, watches, cash registers, stoplights, heart-rate monitors, and more and suddenly the number of available data multiplies n-fold. Thanks to the meteoric rise of cheap data storage solutions, all of that sweet, sweet data can be processed into meaningful---and sometimes invasive---information. After all, data just is information about our world.

Data scientists sometimes discuss data in terms of:

volume: the amount of data
variety: the different forms of data
velocity: the speed at which data accumulates
veracity: the certainty of the data

We won't cover too much about data specifically since that could be a whole series of blog posts on its own. What's important to understand as a developer is that data comes in many varieties, which we'll call types. The most common data types you'll encounter, especially early on, include strings, integers, and booleans. More complex data types include floating-point numbers (a.k.a. decimals), arrays, varchar, timestamps, and more. Different database systems allow different data types, and here's a perfect place to start talking about how we deal with all these different data and data types... it's time to introduce databases!

Databases

While there are many different models for how database systems work, we're going to focus on the model which dominates much of modern software engineering: relational databases. A relational database is a table, almost like a spreadsheet, organized into columns and rows. Note that most of the databases we use today are really pseudo-relational---they don't quite fit and follow the strict tenets of E.F. Codd's original relational model---but we'll treat them as equivalent here.

In relational databases, there are also many different terms depending on your uses, languages, or preferences. Imagine a spreadsheet with a filename, rows, and columns. The file represents our "table" or "relation." The filename should also be unique --- a table has a name that is distinct from all other tables in the database. A row is known as a record or a tuple. There are no duplicate rows. A column can be referred to as an attribute, property, or field. The values of the columns should be the same data-type. Databases contain many tables, and tables have many records and attributes.

Attributes themselves can be either key or non-key. Key attributes are sometimes called candidate keys. A candidate key is any attribute that could be used to uniquely identify a record in a particular table. Typically, a table will assign one of those candidate key as a primary key. A primary key, or main key, is a unique identifier for a record. In pure SQL, we'll typically identify this in our table by specifying id INTEGER PRIMARY KEY in the schema. There are also unique keys. Unlike a primary key they're not used specifically for reference to one single row or record, but they are used to ensure there is only a single entry for items with that particular key. Also unlike primary keys, a table can have multiple unique key columns, and unique keys can be modified to new values. They can also be null.

Unique keys and primary keys ensure that a table doesn't violate an integrity constraint---in this case, to maintain consistency, we don't want two records with the same keys. Primary keys and unique keys, therefore, cannot be duplicated. Candidate keys that are not used as primary keys are sometimes called alternate keys. A record can be referred to in a different table by referencing its primary key; in this case, we call the reference a foreign key. Put otherwise, a foreign key says "Hey, this thing is also over there!" This helps to establish specific relationships between the records in different tables. A foreign key must exist as a primary key in some reference table ---- this is known as referential integrity.

This capacity of tables to be related to one another is why we call these databases, well, relational---the ability to bind two different tables together using foreign keys allows us to map out relations between records in different tables. The possibilities become endless.

There are many kinds of other keys, such as including superkeys, composite keys, and more. Attributes that are not considered keys are known as non-key attributes. The count of all attributes in a table is called the degree. Along with identifying which attributes are key or non-key, we also want to specify the type of data we'll expect to store and retrieve from an attribute.

Earlier we talked about how data comes in different types. Our database needs a way to know what kind of data it can expect. Typing is the practice of explicitly declaring the types of data you intend to store in each column of a table. Typing tells us the available domain of data for the column, field, or attribute. We do this to optimize efficiency and normalize the data. You wouldn't want to be constantly checking, converting, validating data entered into the table; instead, we want to be able to store data in a normalized format that is repeatable and expected. This normalization or consistency across our data types empowers us to calculate, to search, to sort, and to perform many more tasks that would be much more challenging if we were to mingle disparate data types.

Earlier that there were three ingredients to databases: the data itself, a storage system, and a way to interact between the two. Our data, systematized into attributes and records collected into tables, now has its storage system! All that remains is how we get data into the table and back out again... we need an access language!

Access Language

Structured query language is the most common access language for interacting with data and databases. SQL is a domain-specific language (DSL) for looking into databases, updating them, creating them, and much more. It's composed of keywords (by convention, these are capitalized), operators (for comparison or manipulation), and functions (transforms the results for presentation).

Of notable benefit to using SQL is its ability to work across languages. Anything stored in a database is, by nature, reusable. Since most programming languages have libraries that allow us to make use of a relational database, we can, in theory, access it using different languages so long as those languages can write into SQL. Think of SQL as the bridge between your preferred coding language (Java, Ruby, JavaScript, etc) and your database --- it is, in essence, a lingua franca for communicating with a database.

SQL has the ability to perform all CRUD operations on a database. CRUD is short for create, read, update, and delete. SQL allows us to design the database schema (what our tables, rows, and columns will look like). We can then insert records into those tables, select records to read, update them, alter them, transform them, aggregate them, order them, limit results, page results, rewrite them to be printable, and so much more. Selecting data in SQL is known as a query. A query returns a result set which can be filtered further to return a singular answer.

If you are familiar with set theory in mathematics, a lot of the power of tables, and of SQL's ability to manipulate those tables, comes from treating them as sets of data. SQL lets us perform operations akin to unions, intersections, and exceptions in the form of inner joins and outer joins. Joins are just a way to merge multiple tables to select or filter overlapping (or non-overlapping) results.

It is common for non-database-specific engineers to deal with databases. And, to be quite honest, SQL is not the most enjoyable language to work in (YMMV). Fortunately, there are tools in most languages to allow you to write SQL without actually writing any raw SQL. Coupling these so-called adapters with object-oriented languages is especially powerful. We can implement something called object-relational mapping, which lets our applications bind database records to corresponding objects, which gives us access to our full dev toolbelt. By abstracting our data into objects and classes, we gain the ability to do fun and creative things that wouldn't be possible within the databases. More importantly, when we're done doing all of our fun and creative things, we can persist those objects back into our tables as data once more.

Conclusion

Today we touched on the basics of a database management system, from top to bottom. We talked about the three pieces of a DBMS: data, databases, and access languages. We concluded that data are discussed in terms of volume, variety, velocity, and veracity. We spoke about how the relational database model has come to dominate the database management, and how we can use keys in databases to uniquely store and identify records. We also spoke about the power of SQL to manipulate records and tables in our database, and SQL's ability to serve as an intermediary between our higher-level programming languages and our databases' information. We also briefly touched on how adapters and ORMs can allow us to manipulate data as objects and classes within our applications. Hopefully, we clarified how just a few pieces of the giant data puzzle fit together without managing to completely glaze over in confusion!

Refactoring Foodexplorer: Advice from My First Object-Oriented CLI Project

TJ Wright — Sat, 25 Jan 2020 21:21:38 +0000

Overlooked Concepts for Your First CLI Assessment

Today I want to talk about my first CLI project for Flatiron School: Foodexplorer. I want to cover a few mistakes you might make with your first Ruby project by talking about a few of mine and how I fixed them. On the way, we'll also cover some fundamental things to know about executing Ruby, and some questions that came up in my very first code assessment with Flatiron School!

You can familiarize yourself with my project by following the link, checking out the code, or running it on repl.it. However, the advice below is mostly general with examples drawn from my own refactors and codebase for Foodexplorer. While it may be beneficial to check out my code, Ive tried to provide snippets as often as possible to help contextualize things. To put it briefly: Foodexplorer is a command line tool that lets the user navigate through cabinets, create random grocery products, and find out nutritional information about those products. It's a command line version of exploring your kitchen as a kid and finding random products, with the added adult twist of knowing the nutrition data of those items. There are three classes, CLI, Product, and Cabinet. Their functions are what you'd imagine in real life: command-line interface handles input/output, products have nutritional data and belong to cabinets, cabinets have products inside of them (although some are empty!). Simple, right? Right!

This simple project can teach us a lot about good object-oriented design principles and some fundamental programming concepts. Okay, let's dig in!

Single Responsibility Principle

The single responsiblity principle says that every class, module, or method should be responsible for one thing---in other words, an object should be responsible for a single unit of work. What did this look like in Foodexplorer? It is the responsibility of the CLI class to handle user input/output. It is the responsibility of the Product class to create and report itself. It is the job of the Cabinet class to keep track of its associated products. My mistake early on was thinking that the Product class should report its own status, and while this is sort of true its truly a violation of this principle of responsibility. The CLI class handles input/output. It's not my Product class's responsibility to interface with the user; it's the responsibiltiy of the command line interface. Understanding this was a huge revelation when it came to the architecture of my application and how methods should be distributed between classes. It led to a huge minimization in my Product and Cabinet class since their responsibilities were, on the whole, limited.

Separation of Concerns

Separating concerns focusses on the modularity and, in turn, encapsulation. Being modular means that a snippet of code can execute one aspect of a desired functionality. In the service of modularity, I decided that my CLI class of Foodexplorer would have four primary method types:

Splash methods are responsible for introducing a menu or control flow. Their only purpose is to display once when changing menus or entering the program. They are, by design, not meant to be called repeatedly.
Menu methods are responsible for giving menu options. Their purpose is to manage a user's flow through the interface by using user input to make navigation decisions.
Query methods are responsible for asking specialized questions to the user. They are like specialized menus, focussing primarily on using user input to make item-specific selections.
Display or list methods are responsible for handing over output to the user based on their selections and location within the interface.

Categorizing what kind of method I wanted, besides DRY-ing out my code (see below), also made it extraordinarily modular. Methods had everything they needed to execute their role, and that role could be quickly pointed by throughout the program. It also meant I could spot when there was more than one way to display or select the same thing and refactor appropriately, leading to an object architecture that was entirely plug-and-play. (Note: Naming the kinds of methods I was using was verbiage specific to my project. In the Ruby language, there are only class methods and instance methods.)

The second characteristic of separating concerns related to encapsulating information inside of a piece of code. Another way to think of this is as a way of information hiding . In our heirarchy, the Product and Cabinet class know about each other by their very nature, but they aren't concerned with each other. In my original code, the Cabinet class would make its own Product instances; the new Foodexplorer encapsulates this feature by moving the #create_new to the Product class, and calling Product#create_new directly from the CLI. The Cabinet knows about its associated Product instances only by a has_many relationship; otherwise, the details of the Product class are altogether hidden---the Cabinet class never steps into the Product class and vice-versa.

Treating the program as if the CLI class is a "front-end" and the Product/Cabinet classes are the "back-end" led to both a modular and a fully encapsulated program. This architecture will also bode well for us as we move into the principle of Model-View-Controller.

Open/Closed Principle

Speaking of the #create_new method, let's talk about the open/closed principle of object-oriented design! The premise is simple: a system should be open for extension, but closed to modification. In other words, we should be able to extend the abilities and feature-sets of a program without having to change anything we've already established. Obviously, there will always be moments where refactoring to include features will be necessary, but the idea is that in an object's class we want to be able to extend the ability to instantiate new objects from diverse resources. Consider the difference between (a) writing a API.call into an object's initialize method versus (b) writng a self.create_from_api method that pushes an attribute hash into the object's initialize method. If we wanted to include an alternate API, add a scraper, or include user-generated objects, we would have to rewrite the object's initialize altogether. However, in (B) we can simply add a new method, self.create_from_whateverthat does the grunt work before shoveling the attributes into the initialize. Our ability to extend our creation here would be endless! That's the basic premise of the open/closed principle: we can extend abilities without altering old ones.

DRY Code

The nightmare of a codebase's architecture is repetiveness. It's certainly the easiest code smell to notice, but implementing methods to DRY out your code can sometimes be daunting. DRY stands for don't repeat yourself. In the first iteration of Foodexplorer, I had this line show up a lot:

    else
        puts "Hmm, I didn't quite catch that. Let's try again."
        main_menu
    end

It took me far too long to realize that I could simply encapsulate repetition into its own method, #oops and call that method. The refactored version looked more like this:

    else
        oops
        main_menu
    end

After doing that, I realized I could have some fun with it. Who wants to see the same error message over and over and over again? I wrote this into the #oops method:

def oops
    random = rand(0..5)
    if random == 1
        puts "\nOops.. I'm not sure I understood what you were trying to do."
    elsif random == 2
        puts "\nHmm.. looks like you're having a little trouble."
    elsif random == 3
        puts "\nOh no.. I don't think you entered a valid option."
    elsif random == 4
        puts "\nDarn.. you lost me. Let's try that again?"
    else
        puts "\nWhoops.. didn't catch that. Try again?"
    end
end

Now, everytime we see a mistaken entry, we get a different message. This made the application feel more dynamic, as if it was really paying attention. Since I had simply put oops into all the other methods, I could change one spot and watch the entire application become dynamically more interesting.

Functional vs Object-Oriented

With the above design principles in mind, let's talk about a major failure of Foodexplorer's first iteration: it was more functional than objective. There's nothing inherently wrong with that, if you're writing in a language like C++ or Haskell. But if you're in Ruby or Python, you'll want to leave that at the door! It's not that these languages can't support functional programming, but part of the magic of Python or Ruby is that everything is an object. Understanding how to manipulate those objects is absolutely pivotal for a successful object-oriented codebase, although merits for one versus the other are somewhat arguable.

So what did this difference look like in Foodexplorer? Here's a diff from the a refactor that fixed some of the issues above.

Specifically, I want to pay attention to changes to the Cabinet#display_cabinet method, where I've moved from a procedural practice of passing input/selections as arguments to an object-oriented one, where I'm using properties of objects to make things work. First, to note, is that this method is inside of the CLI class. Why? It handles input/output, so it belongs in the class whose responsibility it is to handle input/output. Second, this method has one distinct purpose: it displays the cabinet information. Finally, let's talk about some functional/object-oriented changes: you'll notice the new method #display_cabinet drops the (cabinet_name) parameter. Inside of the method, we also see that the enumerator no longer uses a Product class method and a matching conditional to ensure it prints the right names. Although line 91 and 92 have some object-oriented features, this method is still ultimately manipulating the argument passed into the (cabinet_name) parameter. Notice product.cabinet = cabinet_name and later calling cabinet_contents_query with the (cabinet_name) again passed to another method. Line 91 shows the new method which accomplishes the exact same task using an attr selected_cabinet from the CLI class to log which cabinet or product is selected, rather than using a parameter. This meant the entire method could re-expressed in a single line, calling the #products reader method on the object instance assigned to selected_cabinet and enumerating with the same each.with_index(1). The method finishes the same as before, but drops the (cabinet_name) again from the call to #cabinet_contents_query.

Shebang! Hashpling!

The shebang is a special character sequence in a script file that specifies which interpreter to use. The shebang is always on the first line of the file, and in Ruby is composed of the characters #! followed by the path to the interpreter program. Including env means you do not have to know the absolute path to the Ruby interpreter, because the script will figure it out at runtime!

Return Types

Late into development, I struggled with an issue that had me absolutely lost. My CLI kept halting and catching fire! It would stop, and nothing would happen. I spent hours trying to figure out why nothing would happen... it had worked the day before, and I changed a few things, and suddenly boom nothing. It got through a few I/O runs, then I'd ask it to make a new object and it would freeze. I even went so far as reinstalling my entire Ruby environment to find this bug. The answer was absolutely simple: my code returned nil not the Product object.

It may seem really silly, but understanding return values is a seriously basic step that could save you tons of debugging time. And as frameworks start to pile on, it gets more and more important knowing the intricacies. If you just thought to yourself "Oh, I definitely understand return values!" then great! I compiled a few examples to help check for understanding... make sure you can answer them by reflex!

What is the return value of puts "car"?
What is the return value of pp "car"?
What is the return value of "car"?
What is the return value of car = "Toyota"?
What is the return value of .each?
What is the return value of .collect?
What is the return value of this block?

def return_value
  puts "car"
  "car"
end

What is the return value of this block?

def return_value
  "car"
  return "Toyota"
  puts "car"
end

What is the return value of this block?

def return_value
  car = "Toyota"
  puts car
end

What is the return value of this block?

def return_value
  "car"
  return "Toyota"
  car = "Toyota"
end

Live Code

So, what did it look like when all of this came together? During the live code portion of my CLI assessment, I was asked to code a new feature. Specifically, the ability to calculate the total calories or macronutrients of a (for time's sake) Cabinet instance's contents --- an accumulator. Conceptually, I put aside for a moment how to do it and started by asking myself where should it happen.

Where should I report the information, and where might it be asked for? Obviously, reporting the information was an output and asking for it would be an input: the single responsibility principle tells me that's the job for the CLI class.
Where should I calculate the information? The cabinet's concern is keeping track of what's in it... since the question was about how many calories are in the cabinet, it was a no-brainer that this method should be captured in the Cabinet class. Certainly there's room for argument on this, but understanding why I had created the Cabinet class in the first place is essential to understanding why I thought that would be the most appropriate home. Originally, that class was meant to be a Meal class, and it made sense that meals ought to know their own calorie count. Building the accumulator feature into the psuedo-Meal class meant that meal instances would have a #total_calorie method, and that just made sense.
What information does the accumulator rely upon? It needs to know the Cabinet instances products, #product_list and it needs access to all the product instance's calories attr to summate them.

The whole feature took four lines of addition: one puts line in the CLI class to report the information as output to the user, and these three lines in the Cabinet class:

    def total_calories
        self.product_list.sum { |product| product.calories }
    end

Final Thoughts

Refactoring my project was one of the most eye-opening things I have done so-far. Using design principles like separation of concerns, DRYness, the single responsibility principle, and the open-closed principle after failing to do so led me to truly discover for myself the power of those tools. Having a firm grasp on fundamentals, like return type and the shebang, gave me confidence going forward while also reaffirming how much I have already learned over a few short months. Hopefully this post can give you some more confidence and security in just how much you know now, too!

Creating Foodexplorer v1

TJ Wright — Thu, 19 Dec 2019 06:14:17 +0000

The Original Intent

My intent was to design a simple command line application, called Macrocounter, that could calculate a person's recommended macronutrient ratio for their specific fitness or weight-loss goals. Typically this is broken into three categories: lose weight, maintain weight, gain weight. There's research behind the approach of balancing our intake of proteins, carbs, and fats that support different fitness-specific goals. Using some fun little math formulas developed by researchers, we can take in a user's attributes (hereafter: attr) and use that to calculate their macronutrient ratio. From there, users would then be able to search for a food, display it's macronutrient content, log it to their daily food list, and it would calculate their current intake of nutrients vs their allowable intake. The set-up was simple, and the objectives achievable:

Create a User class with an attr_accessor for name, age, weight, height, goal. Use a formula to determine their ideal macronutrient ratio and set that as a :ratio attr.
Create a Meal class with an attr_accessor for description, protein, carbs, fats, and overall calories.
Create a Product class with an attr_accessor for each individual product and have a belongs_to relationship to the meal class.
The plan looked like this: When the user logged a meal, it would instantiate an object of the Product class. The product class would be responsible for making a search call to the API, the API would return some results (probably limited), and we could select an item. The product would then set the protein, carbs, fats, calories for that particular Product, as well as link it to a meal. The meal class would keep track of the accumulated macros and calories for all the products identified with that particular meal object.

But, if you have played with the CLI gem, you'll immediately notice none of this is there. So what happened to the plan?

The Limitations

Time

The amount of time it would've taken to fully develop out some of these details for this particular project meant it would take a bit longer than it really should take... after all, there's more advanced things to learn that could make this project a whole lot easier, and --- assuming it ever saw the light of day as a useful tool --- most people who would benefit from it probably aren't looking for a command line gems to track their food! Especially one without the utility of persistent user data from session to session.

Scope

The scope of the project was to demonstrate the ability to write Ruby classes that could interact, as well as gather data and assign data from an API or scraper. That goal could be accomplished in a far simpler project.

Data

Using APIs is, at times, unpredictable and can present it's own challenges. In the course of this project, I attempted to use several different APIs. For nutritional information, it's surprisingly difficult to find well-managed, clean, public APIs. Why? Well, there's a lot of money to be made with ulities like this. Adidas, Nike, UnderArmor.... they all have their own nutrition trackers just like mine that need to get data from somewhere. So, obviously, all of those somewheres like to charge money. Can you blame them? That led me to look for some free, public alternatives. Unsurprisingly, the free alternatives had masses of data --- far more than I would need --- and were somewhat complex in their implementations and somewhat lacking in documentation for a project with modest goals like mine. Eventually I landed on the API of the good folks at Spoonacular. Their free version had enough API calls included to be useful, and the data returned was exactly what was needed... almost.

Search

It turns out --- who knew! --- search is hard. After getting the Spoonacular API up and running, writing some methods to allow the user to search for a product, I quickly found out that the results the Spoonacular API returned were... really, kind of awful. I was hoping displaying the first results of a search would land on at least one result that, for demonstration purposes, could approximate something useful. This turned out to be extremely unpredictable... searches for "carrots" would return results like "carrot cake" or "carrot-flavor add-in." Searches for "chicken" returned, as a first result, "buffalo chicken dip." It was clear it would take some work to get the search to be useful, or else it'd be a wasted endeavor.

Intentionally, I allowed the above challenges to limit my project --- after all, if I were truly let loose to create something, we'd be looking at a fully decked-out, killer app! Resisting that urge was practically the most difficult part.

I decided instead to produce a minimum viable product for this project, even it meant jettisoning the utility and practicality of my coveted Macrocounter. The new goal was to create more of a random game, called Foodexplorer. The user would open a cabinet in their kitchen to discover some items, and they could then explore the nutritional value of those items. There was no more logging by the User --- it was suggested that I save this functionality for when we introduce things like databases. There was no more searching --- let's leave that for a bigger project, or at least one with a more useful UI. What remained was the satisfaction of the project's modest goals: manipulate data received from an API or scraper as Ruby objects, including maintaining relationships between different objects.

Producing an MVP

Defining and Ideating

With our new goal in mind, I began dissecting the pieces that would need to fit together to make the gem run. I knew I needed to have at least three classes: the Product, the Cabinet, and the CLI to control the user's flow through the interface. Let's step into each one of these classes, starting with the lowest in the heirarchy.

Product

Products are objects which have nutritional attributes, such as :protein, :fat, :carbs, :calories. They have a :name and they are located in a :cabinet. Initially, when I approached the problem, I didn't include :cabinet as an attribute. Although this should've been immediately obvious, it was something I had overlooked. It wasn't until I began writing a method that would allow the user to look up the products in each cabinet that I realized this would have significant utility. For each of these attributes, I intentionally used an attr_accessor --- that meant each attribute could be written or read. At instantiation, a Product stores the result of an API call to Spoonacular Spooonacular actually provides a huge amount of data in their JSON reply. Since the title and nutrition data I wanted was in a nested hash, I used result["title"] and result["nutrition"]["calories"](etc) to set the Product's attr for each corresponding value.

Cabinet

Cabinets store products. But which products? The Cabinet class was responsible for creating new objects, since a cabinet needed to be opened to see what was in inside! To determine the amount of items inside, I'd pick a random number between 0 and 3. Limiting the amount of products inside each cabinet to three or fewer was a simply pragmatic. The Cabinet class then uses a loop to create a new Product object. On initialization, a product object is generated by randomizing a number up to six digits, interpolating the number into the API call, and returning JSON asssociated with the random ID.

CLI

The CLI class handles the user's flow through the application. It prompts the user for input and uses that input to make decisions about what to do next. It also gives instructions and generally guides the user. It also handles exiting for every possible command.

Testing and Revising

In testing, many issues came to light which I was unprepared for. I'll outline a few of the most pressing concerns that required some quick-witted solutions.

Handling words and integers

I made the choice to give the user the option to use both words and numbers at various points through the CLI gem. This was probably an unnecessary difficulty, but it felt like a more natural way to interact. I would've liked to have made products selectable by their names, as well, but in the end it was just simpler to use numbers for identifying items in lists.

Referring to the products by their cabinet number

Early on, I didn't include a :cabinet attribute for a Product instance. Absentmindedly, I ran into a lot of issues trying to recall which product instances were in which cabinet instances, and I ended up writing some very, very overdone code. After a day or two off from working on the project, I returned to it with new eyes and realized that I had just been spinning my wheels on something that could be solved way simpler! Live and learn.

Nonexistent products

One thing I didn't anticipate was that not all random six-ish digit numbers would return a result. It wasn't until testing my app over and over and over again that I ran into this issue of getting back empty products. I spent a while debugging my code, thinking there was a problem with the way it was returning values from Spoonacular or a problem with the way it was displaying them. What I realized was simply that there was no item for that numeric ID in Spoonacular. I decided to write a new instance method, Product#try_again that would simply retry the randomization procedure if nil was returned. My motivation for using an entirely new method, specifically named try_again, was so that if bash displayed the errors in the traceback, I'd be able to see whether it had been called. Later on during testing, I found another issue with Spoonacular not returning values for some IDs for various other reasons. I decided to rewrite the conditional in the initialize to a case statement that checks result["code"] for errors 400 or 404. If so, they'd call Product#try_again, else they'd run as normal to do the attribute assignment for the instance.

TODO

Although I likely won't develop this project further --- at least, not as a command line tool --- it was important that I include a few notes on functionalities I'd like to see included. Without substantially changing the intention or spirit of Foodexplorer, here's a few things I would add:

Store the Randomized Product ID

It would take all of one or two lines to store the randomized six-ish digit number that the Product creates on initialization to get data. Having this number stores as an ID for each instance of the class would be useful if I were to ever add features to the app that searched through the API's JSON for more information than simply nutritional data --- for example, serving sizes, etc. Not having that value stored means that recalling the full JSON for each product is currently impossible.

Look-Up or Order by Nutrient Content

Using something like a Product.all.sort_by { |product| product.fat } could sort all of the objects by their fat content, for example. I could also use something like Product.all.select { |product| product.fat == input } if I wanted to give the option to look up by an amount of fat, or more likely something like <= or >=. (For what it's worth, in the original Macrocounter gem, this feature would've been useful for allowing users to figure out what else they could eat to fulfill their recommended percentages.)

Search

Obviously, bringing the ability to search through products would be a useful feature. Even in its current implementation, searching would be a fun addition --- after all, you ought to be able to search through your cabinets for something! This feature isn't included since it would really just be some icing on the cake; it was by no means a necessary functionality for Foodexplorer. Since I can't claim any fame to being an expert in RegEx, I would've either spent a huge amount of time working on coming up with good RegEx or using an .select method that iterated through Product.all.name to match characters with the .include? method.

A User and Kitchen Class

I really, really wanted to develop a User class that would allow a Cabinet to be assigned to Kitchen and a Kitchen to be assigned to a User. Although it would've been a fun addition, that level of abstraction for this particular project was really unnecessary --- especially after leaving behind the Macrocounter project.