The Code Dump

A place a coder rants at...

Bad Commit Messages Hall of Shame

| Comments

Too many of us just go through the motions with Git and other version control systems without dedicating enough thought to why we do the things we do. This kind of cargo cult programming is so common I don’t think I’ve seen a single team where this wasn’t the case for some of the members in it.

The Hall of Shame

  • “bug fix”, “more work”, “minor changes”, “oopsie”, “wtf” – These mean nothing. You may as well supply no commit message. Why did you even bother to write it?
  • “Work on feature blah blah” x 20 commits in a row – This is unfortunately aided by different IDEs and tools that suggest your previous commit message automatically. It creates a bunch of commits that are not discernible from one another. Yeah, I get a general topic of what they’re about, but we lost the ability to talk about them without using specific hashes and if you see that these changes for feature “blah blah” introduced a bug you have no easy way to guess which commit did it. You have to start going through the diffs.
  • “Fix BUG-9284” – Bug trackers can be awesome, and if your workplace uses them then it makes a lot of sense to write the ticket number in the commit message. The problem is that writing just that now means that if I’m looking at a commit and trying to understand why a change was done I now have to go to a different system and search that number in it. This is a hassle. I usually copy and paste some part of the description of the bug to the commit message to make it easier for anyone in the future to understand what this change does.
  • “Change X constant to be 10” – These commit messages are a lot like useless comments in code. When the description is just which changes were made it’s just duplicating the code – we can see the diff and see that X was changed from 5 to 10. What we can’t see is why this change was needed.
  • “super long commit message goes here, something like 100 words and lots of characters woohoo!” – Tools care about your commit messages. There’s a convention used by most git tools that prefers the length of the first line in your commit message to be 50 characters or less. Stick to it. It makes it easier to look at the history and means you intentionally put the really important bits in the top line.

Why are you even writing a commit message?

A lot of us got bad habits for commit messages when we first started using a VCS and didn’t understand all the benefits it has. Maybe you originally only worked alone or with a small enough team so that changes were trivial to all of you. But some day you’re going to add another developer that won’t be able to easily look at your cryptic commits and understand what was done. Or your memory will fail 2 years later when you stare at something and have no clue why you did it.

Commits are our aid in times of great need

When do we even look at the commit history?

I use git constantly when I’m in the mud and need help. Did I just notice that someone broke a feature? I’d rather be able to whip up the commit history and spot from the messages which one might be the bad one, instead of having to start searching every damn “BUG-4239” in the issue tracker and open the diff for each “minor changes” commit.

Also, if I’m lost about when something became borked I reach for my favorite tool – git bisect. But how can I easily know what range of commits to use if the last 50 commits were all called “Feature blah blah work”?

Lastly, I constantly rely on the history when making changes to code. I see a line I’m not sure about and I immediately fire up git blame in order to see in what commit it was added, what else was done along this line and, most important of all when done properly, read the commit message that hopefully tells me what I was trying to understand. If all I see is “move call to foo to be before call to bar” I’m hopeless – can I move it back? Was it moved because it broke something? Should all calls to foo everywhere be in this order? I now have to hope whoever committed this remembers why he did the change (pro-tip: or hope you have good tests, wink wink nudge nudge).

Write commit message with a purpose

Good commit messages follow these criterions:

  • They say why you did these changes.
  • They shortly describe what was done so we can effectively glance through the history and find what we need.
  • They are self-contained – It’s great that you have a bug tracker, but don’t make me have to open it to understand why a commit was made.
  • They are in present tense – no more “Fixing buy button disappearance on Mondays” or “Fixed buy button disappearance on Mondays”. The convention is “Fix buy button disappearance on Mondays”.

Repent now

No, you don’t need to delete your repository and start from scratch. Decide that from now on you’ll write commit messages with the attention they deserve. Talk with your team, agree on the guidelines for messages and publicly shame whoever disrespects you with bad commits – hey, it worked for continuous integration!

Testing the Untested

| Comments

I’m quite of a testing nut. TDD gave me a big leap forward in my career. I attribute to it a major part of my ability to tackle big tasks.

I won’t go into it again, you can read some of my thoughts about it here. As the years passed I must admit that I’ve become less of a zealot about this. Yes, I write some code without tests (gasp!). Especially when I crank out prototypes for clients to get fast feedback (after all, a good feedback loop is what TDD is all about).

But, even when I don’t write tests I still do it responsibly. Once the code reaches some stability (and this usually happens after a week or two of development, not months) I add tests as I go along.

This is incredibly important. How many times did you let a spike turn into a big ball of mud that is super hard to test? Having the discipline to act on time is a big part of being a professional.

How should you go about doing this? First, start covering the parts of the code that break the most or that you find hard/scary to change. This means we first add the tests with the biggest bang for the buck.

I tend to add test cases almost as if I were writing the whole thing from scratch in TDD. I’ll write many small test cases and they give me the confidence that everything is in order. I might delete some of these tests later, but this isn’t waste! Once you’re skilled in testing, writing a few more tests is cheap and worth it – even if you delete them two hours later.

An important thing here is to see your damn tests fail. The TDD cycle is red-green-refactor. If you haven’t seen a test fail, how can you tell it’s even working? You need to test your tests.

Yes, you already wrote the code, and so it makes sense that the test is passing. But the solution is stupidly simple: break the code. Find the conditional or whatever that this specific test is checking, change it so it’s invalid and see the test fail with your own eyes. That’s the only way to make sure that it works, checks what you meant it to check, and that the error it produces is decipherable.

Don’t test hard, test well :)

My checklist for upgrading to Angular 1.3

| Comments

Angular’s 1.3 version was released a few months ago. Of course that the moment it was out I tried it with one of the bigger projects we’ve been working on. And of course I saw that so many things were broken (due to dependencies that haven’t caught all the related bugs yet) and just reverted and decided to wait a bit for things to ripen.

A couple of weeks ago I upgraded our app to 1.3 without much trouble. Here are the steps I took to minimize risks of breaking things:

1 – Read Angular’s changelog and search for breaking changes

I opened Angular’s official migration guide and started going over the changes to look for things that we’d have to change in our code. Fortunately, we had very little changes to make in this step.

The only issue was with some change in the semantics of directives with replace: true which broke some of those for us and I had to essentially remove that flag from them. We don’t have a lot of these and for that I’m thankful – especially as they were just deprecated in this release.

2 – Research our dependencies

I went over the dependencies in our bower.json file and checked each:

  1. Check that there’s a new release that mentions Angular 1.3 compatibility
  2. Search the GitHub issues of the project for issues that mention 1.3
  3. Read the package’s changelog to see what breaking changes may have been made recently and update our code accordingly

3 – Update everything

This essentially means updating the values in our bower configuration and installing the new dependencies.

4 – Exploratory testing

I went over the different screens in our app and paid extra attention to making sure our dependencies still worked. For example, that the modals are displayed correctly and that the dropdown menus didn’t break.

In this step I discovered about 3 things that broke that I had to fix. The fixes were relatively straightforward – I opened up the project’s site and found out what was changed or that someone else already tackled these changes (a big advantage to waiting out a couple of months before upgrading).

5 – Run the tests

We have a nice suite of unit tests and some end-to-end tests. I ran them to make sure that everything is in order. To my surprise, these passed without a hitch, except for one small test that had to be fixed (it broke because of changes in ngModelController that affected the API we used for testing, but the feature itself didn’t break).

That’s it!

This was really less exciting and problematic than I feared it might be. I’m happy this went pretty smoothly and allowed us to get on with work and start enjoying the new improvements in Angular without having to waste too much time on the move itself.

Happy coding!

I take it back: Don’t read a book a month

| Comments

About 7 years ago I posted my first post on this blog – One Book A Month. In it I make the point of the importance of reading and constantly learning: the person that stops learning that stops living. I attribute a lot of my success to the fact that I constantly try to learn new things.

But, as with everything, it’s possible to push this too far. I’ve read around 20 books in 2014, listened to hundreds of podcasts and read countless blog posts. I never liked “wasting time” – not a lot of TV watching, not playing games, etc. Instead I had this urge to keep learning.

I recently realized that this habit has become busywork. I kept filling my time. Learning helps, but sometimes enough is enough.

What was I getting out of all of this learning?

After all, does it matter that I’ve read every book on technology X if I never use it? I can keep reading every post Amy Hoy wrote and swallow Just Fucking Ship in a day, but if I never ship what good is it? If I read 10,000 pages, but didn’t act – did I really read anything?

If you have to ship – ship, don’t read

I decided to actively spend less of my time consuming. Even though it is intellectual consuming and not time wasting per se, it sums up to the same result. I will focus more of my time to writing blog posts, side projects, etc. With this, I hope, I will build up once more a habit of shipping fast and often.

Will it make a big difference? Only time will tell, but I believe it will. And don’t get me wrong, I’ll probably still read a handful of books, since that really is my hobby, but I’ll treat it as a hobby and so will make sure it doesn’t eat up too many hours that could have been invested in laying out the bricks to getting myself someplace better.

Swift intro exercises playgrounds

| Comments

Last week I taught a “From Objective-C to Swift” introductory workshop. As part of it I create 3 playgrounds with basic exercises (along with matching playgrounds with solutions). In case you’re reading the Swift iBooks from Apple and want to get your fingers a little dirty, these shouldn’t take more than an hour to complete.

Please leave a comment if you found it helpful, have a better solution to an exercise, or whatever!

Get the exercises

Thoughts on Constraints, Productivity and Creativity

| Comments

You’ve surely heard people say how constraints are sometimes exactly what you need to jumpstart creativity or get more things done. I had a feeling this was indeed the case, but recently noticed how this profoundly influences my work and is part of the reason my business is successful.

Here are some of the ways this comes into play in my life.

Working less but getting more done

When I became a father, about a year ago, my partner and I started working only 7 hour a day, 2-3 days of the week (down from the “standard” in our industry of ~10 hour days). When we started this, we did it expecting and accepting that it means some tasks will take us longer to accomplish.

Surprisingly though, now that months have passed, we both feel that those days are usually our most productive days. Knowing that you have less time makes us actively be on the alert to time wasting. Less time browsing Facebook, more time actually working and staying in the flow.

Also, it means we favor getting shit done over talking all day long. If we see that a discussion is taking too long we just make a decision and roll with it, knowing that we can change course later if necessary. I can’t think of a time this push to just getting things done hurt us.

How we affect our clients

Our rates aren’t on the cheap side, especially as students of the Double Your Freelancing Rate lore. Turns out that our clients make better use of us because of the price.

Every developer implemented probably-useless features and wasted time getting rarely-used functionality to work. We noticed how this kind of prioritizing seemed to be happening less as our rate increased – a bit like having a rocket launcher in Unreal Tournament, you save the ammo for those bosses that are worth it. We do things that matter, and everyone around is happier for it.

Another side effect we noticed is that sometimes just our presence acts as sort of a catalyst for the whole organization, because everyone try to prepare better.

A few months ago we had scheduled a 2-day consulting gig with a company, about their plans for the upcoming months. In the time between scheduling the gig and the actual consulting days the team already did some hard thinking about their current problems and goals that we effectively had half of our job already cut out for us.

They later told us how those 2 days felt super productive, but we know a big part of that was their preparation work since they had a hard constraint – they only had 2 days of our time.

Of course we never intended for this to happen, but it’s quite amazing that sometimes a company will take its own tasks more seriously just because it’s spending more money on it.

A Code Retreat anecdote

This is an interesting micro-example of a constraint and how it helped developers in a specific task.

I facilitated a code retreat last week. During code retreats participants solve Conway’s Game of Life over and over again. That day, after 2 sessions were done, no one got to the point of actually solving the whole problem.

On the 3rd session, I added a new constraint – the world now had to be endless, an infinite grid. No one implemented it that way previously, and intuitively this should have made things harder – after all an infinite grid is more complex than a finite one. But, having this constraint made some of the pairs tackle the problem from a different angle and actually get way ahead of the previous sessions in the constrained, harder case.

As I’m writing this a few more cases come to mind, but I think you get the gist. Yeah, constraints can sometimes work against you (like absurd deadlines that turn a project into a death march) but when used wisely they can turn whole problems around.

Your First WatchKit Glance

| Comments

WatchKit is finally out, and of course I started playing with it right away.

I find it a bit awkward to get my first glance running, since I had to create a custom scheme, understand the watch is an “external display” and restart the app a couple of times. I whipped up a short (and crude) 2.5 minutes video showing just that, in case you wanna get started on the hacking as well!

Happy (WatchKit) coding!

AngularJS 1.3 Taste: Async Validators

| Comments

AngularJS 1.3 is finally released and brought a lot of very cool features. I decided to focus on one that, when you need it, will save you lots of time and hassle.

Prior to 1.3 custom validators were half-baked in Angular. There was no real concept of adding a validator to a field even though forms did have validity states etc. Add to that the case of having validators that take a while to run and you’re in a real jam.

Let’s look at an example. Every decent website sign up form that has a username field also has a validator that checks whether that username is available even before you try to submit the form. Here’s how awesome it would be to do that with the new 1.3 API:

1
2
3
4
5
6
7
8
9
10
11
12
13
<form name="myForm" ng-submit="submit()">
    <label>
        Username:
        <input type="text" ng-model="signup.username" required username-validator>
    </label>

    <label>
        Password:
        <input type="password" ng-model="signup.password" required>
    </label>

    <button type="submit" ng-disabled="myForm.$invalid">Sign Up</button>
</form>

You’ll notice that I added the username-validator directive to the username field. Now let’s see how that’s implemented:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
angular.module('myModule').directive('usernameValidator', function($http, $q) {
    return {
        require: 'ngModel',
        link: function(scope, element, attrs, ngModel) {
            ngModel.$asyncValidators.username = function(modelValue, viewValue) {
                return $http.post('/username-check', {username: viewValue}).then(
                    function(response) {
                        if (!response.data.validUsername) {
                            return $q.reject(response.data.errorMessage);
                        }
                        return true;
                    }
                );
            };
        }
    };
});

Basically it’s just a matter of adding an asynchronous validator on that field. That validator simply performs an HTTP request and according to the response sets the field as valid or not. The mechanism that enables this is plain promises: our validator returns a promise and the field’s validity will remain in “pending” state until the promise is resolved. If it resolves with an error, the field will be marked invalid, otherwise Angular assumes all is well.

But, a caveat we have left in the example above is that it let’s the user attempt to submit the form while we are still waiting for some pending validations to return. That’s because the submit button is only disabled while the form is invalid (myForm.$invalid). While there are pending validations and no invalid fields the form isn’t invalid (yet) and so the button isn’t disabled. The solution is to disable the button also while the form is pending:

1
<button type="submit" ng-disabled="myForm.$invalid || myForm.$pending">Sign Up</button>

And that’s all there’s to it. You can see a live example (with $timeout in order to fake the async operation) on this example here (I actually added in there an example fo rusing the new ngMessages directive).

Happy coding!

Don’t Use Yeoman’s Default Angular File Structure

| Comments

Yeoman is a very handy tool, and I’ve used its angular-generator to generate a basic structure for several new projects before. You should use it if you’d like to have it worry about all of your project’s build process (minification, uglifying, compiling SASS, etc.).

But, in my opinion the default file structure is almost negligent. If you go along with it to create your different controllers and directive you end up with something that looks like this:

app/
    scripts/
        controllers/
            main.js
            foo.js
            bar.js
        directives/
            baz.js
            lolz.js
        services/
            haha.js

Can you say “big ball of mud”?

This is bad, since when creating new entities in your project and arranging them, you shouldn’t put them together based on what Angular component they happen to be implemented with. No, we know this already. File structures should be a tool for grouping components logically. After all, when you need to make a change in the login module, do you want to go hunting for the right files under each directory, or open the “login” directory?

I believe you should strive to a structure that looks more like this:

app/
    scripts/
        login/
            login-page.js
            password-validator.js
        dashboard/
            cool-charts.js
            timeline.js

Do I have to stop using the generators for controllers, directives, etc.?

Yes.

I know, it’s not fun. But as far as I can tell, the generators (e.g. yo angular:controller login) don’t support a different file structure at the moment. It it something that’s planned according to the project’s site.

But it just boils down to a relatively simple template (in case you don’t want to type the boilerplate yourself when creating a new file) and adding a line to index.html, really not that big of a deal if it means I get proper file structure.

Happy coding!

It Depends

| Comments

“Should we use AngularJS, Ember or Backbone?”
“Should we go with Rails, Node or Java for out backend?”
“What is the right programming language to start with?”
“Do we need a mobile app?”
“Should we have Facebook login?”

You probably get these questions and their like all the time. The only right (first) answer to these questions is: It Depends.

I know, it feels like you’re saying you don’t really know, and sometimes people treat it as if you’re trying to be a smart-ass. But, really, it does depend, and giving an answer without considering the specific case is bordering negligence.

The reason we get paid The Big Bucks™ is because we know when a question deserves deeper thought and which considerations should come into play.
That’s the knowledge your clients, boss or colleagues might lack and is what your expertise should be.

Yeah, choosing Java for your server side is rare these days but what if the company is based in an area with lots of Java experts?

Yeah, Facebook login saves a lot of work sometimes, but sometimes having it would just make things really confusing, or even cause your customers to not want to use your product.

So, be proud in knowing when it’s the right call to say “it depends” and not just shoot an off-the-cuff answer. The people you work with will value you much more for knowing that everything has context.