Continuous Improvement in Ruby, Javascript, and Life

Menu

This is one of those reminder posts. I just set up nginx with a Go web application, and I always forget how to do it. Three things are required:

Update nginx.conf to include a sub-directory where the actual conf will be stored

Add an nginx.conf to the sub-directory

Update /etc/hosts with your site name

Update nginx.conf

nginx.conf (in /usr/local/etc/nginx if you installed from homebrew). The include path should be relative to the nginx.conf file. If the nginx.conf file is in the nginx dir, then sites-enabled should be in the nginx dir as well.

Let’s say you want to learn AngularJS, what do you do? You go to Google and you type “Getting started with angularjs”. Like most Google searches the top one or two results is usually exactly what you are looking for. In the case of “getting started with angularjs” the top result is https://docs.angularjs.org/misc/started. Look at that, docs.angularjs.org, that looks very official so you decide to check it out. The upper left hand corner has the current version and build number, so this site must contain documentation for the current build. That’s good, I don’t want to have to fool around with old versions.

The site doesn’t have a lot of information, but it does have a few links. The first link that a newbie is likely to want to view is the “Angular JS Tutorial”. That takes you to this monstrosity of a tutorial, which you would only tackle if you hate yourself and you have a week with nothing to do. So you hit the back button back the home page thinking “If only they had something easier that I could start with, you know, like a Build a Blog (1st result) or Build a Todo list (1st result)”.

Then you see it: a link to “Introduction to AngularJS”, which takes you to a video. It’s not a bad video however there are two problems with it:

The guy rockets through the video, presumably to keep it under 15 minutes

The code in the video does not work with the current version of AngularJS. Yep, the first result of a Google search for a Google Javascript Framework contains links to a huge Tutorial that would take a week to get through and a non-working introductory tutorial video. Nice work guys, way to stay on top of things.

AngularJS is becoming quite popular and it has its good parts and its bad parts and this isn’t the first post to complain about the documentation. Almost every criticism of Angular will list shitty documentation as one of the top one or two issues.

However, this post is going to go one step further. Your old pal Mike has created code that matches the intro video word for word, only it is up to date with the latest stable build of AngularJS. You can find the code here: https://github.com/hoitomt/angular-intro-1.3.11. Watch the video but use the code from this Github repo. Of course this repo will age, it might even be obsolete by the time you read this. I’ll see what I can do about keeping it up to date.

One of the (many) brilliant things that the people affiliated with Ruby on Rails have done is to create excellent documentation. Specifically the tutorial that is intended to introduce newcomers to the Rails framework and Ruby. My first recollection of the Rails newbie tutorial was a pizza tutorial on O’Reilly. This was replaced by a Create a Blog in 15 minutes tutorial somewhere around version 2.2 of Rails. Most recently the promise of “15 minutes” has been removed from the tutorial, but it is still as good an introduction to a programming topic as you will find. I would go so far as to say that “Create a Blog in 15 minutes” tutorial is one of the primary reasons that Rails, and by extension Ruby, became so popular.

The blog tutorial introduce new users to most of the features of a full-featured web framework: Model-View-Controller, database interaction, development environment (including dev server) and almost everything in between. Any new framework, that is interested in gaining users, should add a “Create a Blog Post” tutorial for new users. If the framework is not fully featured then sample bits (server, database, whatever is missing from the framework) should be shipped with the framework so that the full end-to-end experience can be modeled by the tutorial.

The popular JS frameworks (AngularJs, EmberJs, MeteorJs) use ToDo applications on their Getting Started pages. Django goes with a Web Poll application, NodeJs (not really a framework) punts the user over to nodeschool.io. The ToDo app is fine, as long as a complete solution (UI -> Database persistence) can be built in a short period of time. That’s the beauty of the Rails “Create a Blog” application. An end to end solution can be built in about 15 minutes.

My Github commit history is looking weak these days, only 92 commits over the past year. Oh sure, when I’m logged in it looks pretty good, over 1,500 commits (when you’re logged in you see all of your commits, including those to private repos). It’s important for software engineers to write code, and by extension, learn new things. Hacker News is filled with posts about amazing side projects. I’m so jealous when I read about them. I know that I could create some amazing projects too if I could just… open… my …. laptop…. Phew, that was tough, I swear the lid of this thing must weigh a ton.

Now for the part where I justify my lack of after hours coding. My motivation works on an annual cycle. Starting somewhere around February I start to gain some motivation to start writing code. My commit history bears this out, it’s loaded toward the beginning of the year (lightly loaded: like I said, 92 commits). This motivation lasts until mid summer. Around mid to late summer my motivation takes a nosedive and I don’t do much coding at all.

Do you know what else starts in mid to late summer: American football season and the American school year. I am a huge football fan. Typically I don’t watch TV at all, however during football season I’ll watch games. And with the NFL putting games on Thursday, Sunday, and Monday nights, that’s three nights spent not coding. In addition to being a football fan, I’m also a father of 3. Summers are a double-edged sword. The kids are around during the day which makes my work environment (my home) louder, which is bad. However, since they don’t have to get up early for school, I don’t have to get up early to get them ready for school. As a result I’m able to work later at night on side projects and I’m still better rested because I can sleep in a bit.

With the Super Bowl coming up, I’m hoping to get started on something in a few weeks. When I’m not working on a side project, I start to feel guilty. There is a strong feeling in my gut that I need to keep improving. I used to work for a large health insurance company with a crappy culture, and one thing that stuck with me from working there is that you were either “Moving up or moving out”. The saying referred to the corporate ladder, but the saying is apt to software engineering as well. If you aren’t learning, then you’re stagnating and losing ground to your competition.

To be clear: I feel very good about my overall commit history. I’ve made substantial commits across multiple languages to multiple private repositories. But you always want to put your best foot forward to anybody that happens to come across your profile for one reason or another. Also there are some apps that I wish existed, and your own itch scratcher makes the best side project.

If it seems like I worry a lot about my standing in relation to others, that’s partially true. I think it’s more a fact that I always want to have a job. Preferably a job of my own choosing. I work for a great company right now, but you never know what the future holds. Another part of being a father is that you don’t want to be unemployed at any point with college tuition looming

A new year is upon us and with it comes New Year’s resolutions. One of my resolutions for this year is to blog at least once per week. I’ve read a few people disparaging New Year’s resolutions, but I’ve found them to be somewhat motivating.

Another thing that motivates me is competition. Not the overt type of head to head competition that we experience when competing in a sport or contest. But the more subtle type of competition where I want to be the smartest person in the room. I think most software engineers feel this way; it has driven most of us for our entire lives. We couldn’t always be the most athletic or the best looking, but when it came to the acquisition of knowledge (primarily in school), we knew we had a shot at winning.

Life as a software engineer is similar to school. There is a constant stream of new things to learn (Hacker News, Twitter, blogs, Github, startup celebrations, etc…) where we can chose to to be competitive. As a software engineer it is incredibly easy, and actually preferable, to be constantly confronted with things that you don’t know.

However, once you encounter something that you don’t know you have to make a choice about what to do with this new piece of information. Should you find out more about it to broaden your knowledge? Should you ignore it? Should you minimize it and poke fun at people who are interested in it? Whatever your reaction, two things have happened: you have just been confronted with something that you don’t know and somebody knows a lot more about than you do.

And that’s the rub – somebody has more knowledge than you do. If you didn’t encounter this new piece of information, you wouldn’t know this person existed. But now that you know that they exist, you are immediately in competition with them. Sometimes it’s easy – Lebron James can jump from the free throw line and dunk a basketball and I can’t do that. However I’m not a professional basketball player so I don’t need to be competitive with him.

However what happens when you are confronted with something that you didn’t know in a field where you call yourself a professional? When I read a post by a person doing something new in Ruby I feel some competition with that person. I say things to myself like “pfftt, I knew that…” or “Oh damn, I didn’t know that, I better read up on that”. Either way, it’s a competitive reaction where I don’t want that person to be better at something than me.

I’m guessing that being competitive is hard-wired into us as human beings. When confronted with another human being that has something we don’t we are either dismissive (“I don’t need that”) or competitive (“I’m going to get that”). However the negative side of competition is that it is easy to spin yourself into a tizzy and get caught up in it. I think that breeds a constant feeling of inadequacy and helps to explain why some people are so mean on the Internet, they don’t feel good enough and worry that they may never be good enough so they need to take people down in order to compete.

However, it is the thirst for knowledge, the understanding that there is more to learn, and the constant curiosity that we have that will determine our happiness and success. Those that believe they have mastery, and have nothing more to learn, are bound to be surpassed by the competitive and the curious.

This post builds off of code that was created in the previous post. The complete source code for this blog post is available on github with accompanying demo.

In the last post we created a Gruntfile that ran a web server for developing web applications. That was just the first building block in our rocking web development setup. Now we’re going to introduce modern tools into the development setup. Javascript, CSS, and HTML are fine but over the past 5 years there has been some real innovation in “front-end” web development. CoffeeScript, Sass, and HAML are three excellent technologies that will increase your developer happiness.

If you aren’t familiar with these languages you may be thinking of them only as syntactic sugar. Well, you better sit down, not only do you get syntactic sugar, you get all sorts of other good stuff. CoffeeScript (for loop syntax, trailing conditionals, the “existential” operator (question mark – ?), switch statements, variable hoisting) brings so much to the table. Perhaps the best thing about CoffeeScript is that it actually has the power to make Javascript fun to write… crazy, right?

Sass (mixins, variables, nesting, partials) is almost a must-have for CSS development. Sass has a couple of competitors that are supposed to be quite good; like Less or SCSS. But for our purposes Sass rocks. Haml is primarily syntactic sugar, but it is so sugary delicious that you’ll forget how you wore the < and > of your keyboard.

Both Sass and Haml require Ruby, version greater than or equal to 1.9.1. Type ruby -v from the command line to determine what version of Ruby you have. If you need to upgrade Ruby (ruby -v returned a version less than 1.9.1) then upgrade all the way to 2.1.

Once you have Ruby installed you have to install the sass and haml gems.

gem install sass
gem install haml

Also CoffeeScript requires that the coffee-script compiler is installed npm install -g coffee-script and you’re ready to roll

Let’s get started

First we’re going to change the directory structure to match the convention of more modern web apps. Setup a structure like this:

The coffeescript files will go in app/coffeescript and the sass files will go in app/stylesheets. The compiled files will end up the public directory.

Next add the dependencies to your package.json. We’ll start with CoffeeScript. There are different packages for compiling CoffeeScript with Grunt, I like the grunt-contrib projects so we’ll use grunt-contrib-coffee. Add grunt-contrib-clean and grunt-contrib-coffee to your package.json. grunt-contrib-clean is a nice task for cleaning out your assets before building.

This is the entire Gruntfile.js. It’s a lot to look at but I wanted to point out a few things. First a clean task and a coffee task have been added. The clean task will remove all files from the specified directories (public/javascripts and public/stylesheets). The coffee task will compile all files with a .coffee extension in the app/coffeescript directory. It will put the compiled files into the dest directory with the ext extension, in this case it is public/javascripts with the .js extension.

The web server starts on port 4000. When you visit the site an alert should display with “Starbucks!”

The coffeescript file will be compiled as a javascript file into public/javascripts

The coffeescript file is being watched for changes. Change the coffeescript file to alert "Dunkin Donuts!". Notice that your terminal log will display a message that your coffee file has been compiled. Reload localhost:4000 and the alert message should be changed to “Dunkin Donuts!”

Pretty cool, right? That’s the general idea with Grunt. Most of the grunt configuration is the same across libraries. Let’s add Sass support next.

Run the grunt command and your stylesheet will compile into public/stylesheets/style.css.

Let’s add haml now. This will require a reorganization of the project. Create an app/views directory to store your haml files. Instead of updating package.json directly, let’s use the npm shortcut for installing and updating package.json at the same time npm install grunt-contrib-haml --save-dev. Notice that grunt-contrib-haml has been added to package.json, very cool!

Now for the Gruntfile.js configuration. This looks very similar to the CoffeeScript configuration and the Sass configuration, that’s by design in Grunt. NOTE the change to the connect options, we want to look in the public directory now, not the root directory

You can delete index.html in your root directory. Once you run grunt there will be an index.html compiled from app/views/index.haml file into the public directory.

Go ahead and fire it up with grunt. If all went according to plan you should see the index.html file in the public directory along with the coffeescript and sass files compiled in the public/javascripts and public/stylesheets directories respectively. Make sure to check the site at http://localhost:4000. Was that totally awesome or what!?

When developing a web application it is very helpful to run the application on an actual web server. The javascript community has built some really excellent tools in the last 5 years that make it very easy to do just that.

Grunt is “the javascript task runner”. What the heck does that mean? It means that a single command grunt can be used to kick off multiple commands and watchers. This is incredibly helpful when developing “modern” web applications where you may want to use coffeescript and sass instead of javascript and css and run the application on a web server. If you are familiar with Ruby on Rails we are going to create something similar to rails s.

This post will show you how to get started using node.js and Grunt to create an application server for hosting html and css. This post is not going to go over installing node.js. Here is a nice overview if you’re interested. Let’s get started

Grunt

First install Grunt npm install -g grunt-cli. The -g flag tells npm to install grunt globally on your machine. This is cool for Grunt, we want all applications to have access to it.

After installing grunt, create a package.json file and Gruntfile.js file in your application root. The package.json file is used by node.js to install dependencies and the Gruntfile.js a configuration file that tells grunt what to do.

After adding package.json and gruntfile.js run npm install. Notice that a node_modules directory is automatically created. Node installs all of your project’s dependencies in that directory. So far only grunt is installed.

This is the basic setup. All additional dependencies will be added to these two files. Dependencies are specified by adding one line to the package.json file in the devDependencies block, and then update Gruntfile.js with the configuration and runtime information.

We added a connect task and a watch task to the grunt file. The connect task starts a server on port 4000 and the server will look in the root directory (./) for the html files. Then we told grunt where to find those tasks (loadNpmTasks). Finally we added the connect task and the watch task to the the default command so that when you run grunt it will run those tasks. Add an index.html file to the root directory so that you have something look at when you run the server.

Sometimes you just want to set up a quick website and it isn’t feasible to share your localhost. Github pages are a great way to do just that. The following walks you through the setup for a Github page.

Let’s get started:

Create Your Github Page

Log into GitHub and create your GitHub repository.

Give your repository a name and description and then follow the directions for creating your new repository. The github repo for this tutorial will be called gh-data-1

As part of the setup process you will create a local folder for your project, initialize it for git and push it to your GitHub account. When you finish the setup process, there should be a README.md in your GitHub repository

In your local repository, create a new branch called gh-pages. git checkout -b gh-pages

Add an index.html file in your local repository like the one below – just a blank template with a heading

This post was originally titled “This site is moving”. However, after moving, I’m now back at WordPress.com. I hadn’t realized that WordPress supported the Markdown syntax, which became a requirement for my blogging. blog.hoitomt.com is still a new URL which will give me more flexibility in the future.

I have another one with Grunt, Bower, Flight, Coffeescript, Sass, and RequireJs (also jQuery Mobile). This project doesn’t have any Ruby. It is built up into a project but you can strip out the jQuery Mobile stuff to get to the essence of the project. As a side note I started down the path of Gulp (too new) and Browserify (couldn’t cleanly integrate Flight and Flight was more important than Browserify). But I ended up coming back to RequireJs