Friday, March 20, 2015

Nexus 9, focused writing, and more

About three weeks ago, I got a Nexus 9 and its accompanying Folio case+keyboard at work with the main goal of drive-testing Google's mobile apps.

Being "free" hardware for testing I could not turn it down, but at first I honestly was not sure what to do with it: I already got a Nexus 10 last year and exchanged it soon after for a Nexus 7 because I did not did not like its bulky feeling. The Nexus 7, on the other hand, is the perfect size for reading news, articles, and books, which is basically the only thing I (used to) do with the tablet.

The Nexus 9

Let me say upfront that the Nexus 9 is a really nice tablet. I have been carrying it around every day since I got it just because I want to use it—I'll get to why soon; bear with me for a second.

Hardware-wise, the tablet looks great and feels well-finished, which is something I could not have said of the Nexus 10. The screen is gorgeous and, what's interesting is that its 4:3 aspect ratio feels just right. (Yes, yes, this is the aspect ratio all screens used to have back in the day. Going back to basics?)

Software-wise... we have Android Lollipop here and, well, let's just say I am not impressed. The hardware in the Nexus 9 is more powerful than what I've got on my Nexus 7 so the tablet is indeed more fluid (how could it not)... but it still feels sluggish in general. Anyway...

The Folio keyboard

I have mixed feelings about the Folio keyboard+case combo.

As a case, I am always afraid it won't do its job because it attaches to the tablet purely with magnets so I'll better not drop it on the floor, ever. On the other hand, this works great should you need to attach your tablet to your fridge; keep that in mind.

As a keyboard, the layout is cramped due to the keyboard's size—almost like a full-sized keyboard but not really; I suspect that if you have big hands (I don't), you won't enjoy typing on this. However, the overall feeling of the keys is reasonably good for a chicklet keyboard, which permits touch-typing at decent speeds.

Unfortunately, the designers of the Folio have gotten this "view" of how things should be in the Android world that I personally cannot understand. No Caps Lock? OK, I can let that go because I can't really code comfortably in this thing... but no ESC key? Really? This is a great keyboard... except it isn't because no ESC key means there is no good way to use SSH (assuming you are a vi(1) user, or a set -o vi user). In fact, if it wasn't for this little detail, this device would be a great on-the-road SSH client.

Lastly, little-known (?) fact: the Folio's keyboard is completely useless on metallic surfaces. If you happen to place it on a metallic table, the circuitry gets confused thinking that you have folded the case and shuts the keyboard off; huge problem for me at work where many relaxation areas have metallic tables. Watch out for you local cafe's tables as well!

No trackpad?

The Folio does not have a trackpad, nor a pointing stick, nor a trackball: that's correct, no pointing device. Or does it?

For the first couple of days, the lack of a trackpad or similar device was annoying. I am extremely used to my MacBook Pro's trackpad and my Magic Mouse with its support for gestures, and none of this was to be seen on this setup.

Except... hold on... there is a touch screen! The feeling of raising a hand to touch the Nexus 9's screen was odd at first, particularly because I hate poking at computer screens due to how dirty they get. But this is something you get used to quickly, very very quickly. The ability to just poke at things feels natural and turns out to be quite useful. In fact, I have caught myself poking at my MacBook's screen once or twice already. Oops!

And, finally, the use case

So what could I use this device for? I didn't know what to do with it really, but I did want to give it a honest try.

Read email? It is good enough, but not as convenient as a desktop email client when you receive hundreds of messages per day. Read books? It's quite heavy and big: the Nexus 7 fits the bill much better. Coding or systems administration? See the issues with SSH above. Watching videos? I have a Chromecast, thank you very much.

This device did not provide me anything that I could not do with any of my other devices: in fact, Android, for a power user, feels limiting: the inability to see more than one app at once, the sluggishness of switching between already-open apps, and the reduced set of supported keystrokes makes some tasks just too difficult.

But I think I discovered the true potential of a tablet with a keyboard (for me, that is): writing. Nonstop writing. And by that I mean no copyediting; just purely writing text without applying any fancy formatting, nor messing with the layout of an article, nor anything else.

Why? Because the whole setup provides an immersive experience to whatever you are doing: apps are full screen and notifications can be easily disabled and/or ignored. The keyboard may surely lack special keys, but it has all you need to type text. With the right writing app, it is really easy to get in the flow and to be freed from constant distractions.

In fact, I have already drafted multiple articles for work and for this blog much faster than I could have on my laptop or workstation. It is that great. For pure article drafting, I am in love.

The killer app: JotterPad

And what can you write with?

My first attempt was to use Drive Docs—Google's full-blown word processor—because it comes pre-installed. Yes, it works, but it has a "problem": Docs has enough features to be distracting. Because the features are there, I invariably get sucked into setting the right typeface, or the right heading structure... As any good writer (not me) will tell you, avoiding all editing during the initial stages of writing is a very good way to create a first draft: a braindump you can later iterate on.

So I went out to research "plain-text" writing apps, and offline at that if at all possible. I tested a bunch and there is one that quickly caught my attention: JotterPad.

JotterPad is this little text editor that follows what-I-think-are all the Material Design guidelines and thus flows correctly in the Android Lollipop environment. It is a simple app that just "feels right" and just works, which is something hard to find these days sadly.

Feature-wise, JotterPad is very limited, but I do think that this is its killer point. A lightweight app that behaves nicely and does its advertised job correctly. With JotterPad and with its "Typewriter mode" setting enabled, you can write pages and pages non-stop without even realizing. Seriously, if you have anything to write and you have your tablet around, give this little app a try.

(I know, I know, this is a sales pitch. But, in fact, this particular app is what triggered me to write this article in the first place and the authors are very receptive to feedback. So they kinda deserve it!)


So yes, I now think that a tablet operating system with a real keyboard has one specific use-case for me: focused work and, in particular, distraction-free writing. Your mileage will certainly vary, but those are my current thoughts regarding this device and software combination.

(Numbers? This post clocks at about 1250 words and I jotted down the first 1000-word draft in like 30 minutes! That's about 65 WPM, which I think is decent considering that this was not just typing: it was composing text from scratch.)

Saturday, February 28, 2015

Kyua turns parallel

After three months of intensive work on Kyua's executor Git branch, I am happy to announce that the new execution engine, whose crown feature is the ability to run test cases in parallel, has just landed in master and passes all self-tests!

You can head over to the commit message for more details on the merge, read the NEWS entries, and skim throught the history of the executor branch to understand how this feature has been built.

One caveat: the history will look surprisingly short for a project that has spanned over three months. The reason is that, in the executor branch, I have routinely been using git rebase -i master to build a reduced set of changes that tell the story behind the implementation without distracting commits of the kind "Fix this little bug I forgot about" here and there. An unfortunate side-effect of this is that the temporal history of the commits makes no sense, and also that all the work I've been doing is not properly accounted for in GitHub's nice activity graphs; oh well, I consider a sane semantical history more important than these tiny details.

Why is this work important? Why is running tests in parallel such a big deal?

First, because the computing industry has fully moved into multiprocessor systems and thus taking advantage of multiple cores is something that any piece of modern software should do. As a little fun fact, Kyua is now able to stress my Mac Mini when running tests, spinning its fans to the maximum; this did not happen at all before.

But second, and I would say more importantly, because many tests are not resource-hungry or the system resources they stress do not overlap the resources used by other tests. For example: a significant number of tests are penalized by disk and time delays in them, which in turn cause the whole test suite to run for much longer than it would otherwise. Parallelization allows these long-running but not-heavy tests to run without blocking forward progress.

Let me also add that a secondary goal of this work is to optimize the inner workings of Kyua by reducing the system call overhead. In particular, eliminating one fork(2) call from every test case has been an explicit design goal. This especially helps Kyua when running on OS X, as fork is particularly expensive on the Darwin kernel (yes, citation needed).

As a very unscientific example: running the Kyua, ATF, Lutok, and shtk test suites with the old sequential execution engine takes about 2 minutes and 15 seconds in my dual-core FreeBSD virtual machine running on a dual-core Mac Mini. With the new implementation, the total run time goes down to 1 minute and 3 seconds using a parallelism setting of 4. Pretty cool I would say, but your mileage may (will) vary!

Are we done yet?

The merge of the executor branch marks the beginning of a major restructuring of Kyua's internals. As things are today, only the kyua test command has been switched to using the new execution engine, and not fully: only the execution of the test's body and cleanup routines happen through the executor; listing of test cases still happens as it did before. Similarly, both kyua list and kyua debug still use the out-of-process, testers-based, sequential implementation.

Therefore, there is a bunch of tricky work left to be done: the old test case execution engine (the runner plus the out-of-process testers) need to be fully removed, which in turn means that their functionality has to first be integrated into the new executor; there is a need for a feature to explicitly mark test programs as "exclusive", which is a prerequisite for tests that modify system-wide settings (as is done in the FreeBSD test suite); and an important regression needs to be fixed.

So... if we are not done, why merge now?

Because the current code is complete enough as a first piece of the whole puzzle. Even if the implementation does not yet meet my personal quality standards, the behavior of the code is already 80% of the way to my goal of fully switching to the new execution backend. You, as an end user, care about the behavior (not so much about the implementation), so by doing the merge now you can already start taking advantage of the new parallel execution functionality.

Also, because I am tired of managing a relatively large set of commits with git rebase -i. At this point, the set of commits that build the executor provide a good foundation for the code and its design. From now on, any other improvements to this codebase, such as the addition of new features or the correction of the existing regressions, should be properly tracked in the Git history.

And lastly because, at the beginning of 2015, I set myself the personal goal of getting this code merged by the end of February... so I just made the deadline! Which reminds me I gotta plan how the year's timeline looks like to reach Kyua 1.0.

Can I try it?

Of course! Please do!

There is no release available yet, but you can obviously fetch the code from the GitHub project page and and build it on your own! If you do that, do not forget to set parallelism=4 (or some other value greater than 1) in your ~/.kyua/kyua.conf file to enable the new behavior.

In fact, I am not going to cut a new release just yet because some of the issues mentioned above are of the "release-blocking" severity and thus must be resolved first. What I am going to do, though, is file bugs for each known issue so that they can be properly tracked.

Have fun and please share any feedback you may have!

Monday, February 16, 2015

Unused parameters in C and C++

Today I would like to dive into the topic of unused parameters in C and C++: why they may happen and how to properly deal with them—because smart compilers will warn you about their presence should you enable -Wunused-parameter or -Wextra, and even error out if you are brave enough to use -Werror.

Why may unused parameters appear?

You would think that unused parameters should never exist: if the parameter is not necessary as an input, it should not be there in the first place! That's a pretty good argument, but it does not hold when polymorphism enters the picture: if you want to have different implementations of a single API, such API will have to provide, on input, a superset of all the data required by all the possible implementations.

The obvious case of the above is having an abstract method implemented by more than one subclass (which you can think of as a function pointer within a struct in the case of C). In this scenario, the caller of this abstract method may be handling a generic condition but the various specific implementations may or may not use all the input data.

Our example

An example taken straight from Kyua is the compute_result method, whose purpose is to determine the status of a test case after termination based on the outputs of the test program, including: the program's exit code, its standard output, its standard error, and files that may be left in the transient work directory. The signature of this abstract method looks like this:

virtual model::test_result compute_result(
    const optional< process::status >& status,
    const fs::path& work_directory,
    const fs::path& stdout_path,
    const fs::path& stderr_path) const = 0;

Kyua implements this interface three times: one for plain test programs, one for ATF-based test programs, and one for TAP-compliant test programs. This interface receives all test-related post-termination data as inputs so that the different implementations can examine any parts (possibly not all) they require to compute the result.

In concrete terms: the plain interface only looks at the exit status; the ATF interface looks both at the exit status and at a file that is left in the work directory; and the TAP interface looks both at the exit status and the standard output of the program.

When you face an scenario like this where you have a generic method, it is clear that your code will end up with functions that receive some parameters that they do not need to use. This is alright. However, as obvious as it may be to you, the compiler does not know that and therefore assumes a coding error, warning you along the way. Not helpful.

Two simple but unsuitable alternatives

A first mechanism around this, which only works in C++, is to omit the parameter name in the function definition. Unfortunately, doing so means you cannot reference the parameter by name any longer in your documentation and, furthermore, this solution does not work for C.

A second mechanism is to introduce side-effect free statements in your code of the form (void)unused_argument_name;. Doing this is extremely ugly (for starters, you have to remember to keep such statements in sync with reality) and I fear is not guaranteed to silence the compiler—because, well, the compiler will spot a spurious statement and could warn about it as well.

Because these two solutions are suboptimal, I am not going to invest any more time on them. Fortunately, there is a third alternative.

Tagging unused parameters with compiler attributes

The third and best mechanism around this is to explicitly tag the unused parameters with the __attribute__((unused)) GCC extension as follows:

model::test_result compute_result(
    const optional< process::status >& status,
    const fs::path& work_directory __attribute__((unused)),
    const fs::path& stdout_path __attribute__((unused)),
    const fs::path& stderr_path __attribute__((unused))) const;

But this, as shown, is not portable. How can you make it so?

Making the code portable

If you want your code to work portably across compilers, then you have to go a bit further because the __attribute__ decorators are not standard. The most basic abstraction macro you'd think of is as follows:

#define UTILS_UNUSED __attribute__((unused))

... which you could parameterize as:


... so that your script could determine what the right mechanism to mark a value as unused in your platform is and perform the replacement. This is not trivial, so take a look at Kyua's compiler-features.m4 for to get some ideas.

Such a simple macro then lets you write:

model::test_result compute_result(
    const optional< process::status >& status,
    const fs::path& work_directory UTILS_UNUSED,
    const fs::path& stdout_path UTILS_UNUSED,
    const fs::path& stderr_path UTILS_UNUSED) const;

... which gets us most of the way there, but not fully.

Going further

The UTILS_UNUSED macro shown above lets the compiler know that the argument may be unused and that this is acceptable. Unfortunately, if an argument is marked as unused but it is actually used, the compiler will not tell you about it. Such a thing can happen once you modify the code months down the road and forget to modify the function signature. If this happens, it is a recipe for obscure issues, if only because you will confuse other programmers when they read the code and cannot really understand the intent behind the attribute declaration.

My trick to fix this, which I've been using successfully for various years, is to define a macro that also wraps the argument name; say: UTILS_UNUSED_PARAM(stdout_path). This macro does two things: first, it abstracts the definition of the attribute so that configure may strip it out if the attribute is not supported by the underlying compiler; and, second and more importantly, it renames the given argument by prefixing it with the unused_ string. This renaming is where the beauty lies: the name change will forbid you from using the parameter via its given name and thus, whenever you have to start using the parameter, you will very well know to remove the macro from the function definition. Has worked every single time since!

Here is how the macro looks like (straight from Kyua's file):

#define UTILS_UNUSED_PARAM(name) unused_ ## name UTILS_UNUSED

And here is how the macro would be used in our example above:

/// This is a Doxygen-style docstring.
/// Note how, in this comment, we must refer to our unused
/// parameters via their modified name.  This also spills to our
/// public API documentation, making it crystal-clear to the
/// reader that these parameters are not used.  Because we are
/// documenting here a specific implementation of the API and not
/// its abstract signature, it is reasonable to tell such details
/// to the user.
/// \param status Status of the exit process.
/// \param unused_work_directory An unused parameter!
/// \param unused_stdout_path Another unused parameter!
/// \param unused_stderr_path Yet another unused parameter!
/// \return The computed test result.
model::test_result compute_result(
    const optional< process::status >& status,
    const fs::path& UTILS_UNUSED_PARAM(work_directory),
    const fs::path& UTILS_UNUSED_PARAM(stdout_path),
    const fs::path& UTILS_UNUSED_PARAM(stderr_path)) const;

What about Doxygen?

As I just mentioned Doxygen above, there is one extra trick to get our macros working during the documentation extraction phase. Because Doxygen does not implement a full-blown C/C++ parser—although I wish it did, and nowadays this is relatively easy thanks to LLVM!—you have to tell Doxygen how to interpret the macro. Do so with the following code to the Doxyfile control file:

PREDEFINED += "UTILS_UNUSED_PARAM(name)=unused_ ## name"

So, what about you? Do you keep your code warning-free by applying similar techniques?

Thursday, February 05, 2015

One month in with Android Wear

Or: A review of the LG G Watch.

Right before the Christmas holidays, I was gifted an LG G Watch Black Titan, a relatively simple smartwatch that sports the new Android Wear operating system:

After over a month of daily use, I am now comfortable about writing about my impressions. But, before doing that, let me set this review in the right context.


Sometime last summer, the continuous interruptions from my phone ended up irritating me significantly. It seems like pretty much any app you install these days insists on notifying you of their super-important stuff at any time (reminds me of the beginning of the Windows 95 era and the poison that all the apps that registered themselves in the taskbar notification area were—or still are). In an attempt to minimize the annoyances without going back to a dumbphone (which I actually considered!), I ended up doing two things: first, disabling as many of the notifications as possible; and, second, starting to wear a regular watch again to minimize the times I compulsively looked at my phone just to check the time. You know, checking the time is enough to suck you into looking at random online content if there are any pending notifications you did not know about.

As you can imagine knowing this, when I received the smartwatch my first thought was that I would not like it: I would not tolerate being bothered by more intrusive, "on-your-face" notifications. That said, there was one feature compelling enough to convince me of giving it a try: Strava—the sports-tracking app that I use to record bike routes and runs—had a plug-in for Android Wear, and the ability to have quick access to my statistics in the middle of an activity sounded rather cool.

Also, let's face it: having been given a shiny new toy, I could really not resist trying out the LG G Watch so I started wearing it exclusively to have first-hand (haha, pun intended) knowledge of what this new technology has to offer. Spoiler alert: I confess that I am enjoying this experience more than I originally envisioned. Let's see why.

Poor battery life... not?

The first thing people like to mock about these new smartwatches is the fact that they need to be charged every day. Yes, so what? I have yet to find that to be a problem.

For starters, the battery lasts a whole day just fine. If I wear and use the watch on those long days that span from 8am to 10pm, the watch still has, easily, 50% battery left if not more. I don't see it "dying" with normal use during a regular day. Even then, should you forget to charge the watch overnight, you can give it a quick boost during your morning home routine and that will probably charge it enough to survive throughout your day.

Those facts overcome the worry of running out of batter midday and being left with a silly brick on your wrist, but you will still need to charge the watch every day. That said... I don't know about you, but I cannot sleep wearing a watch any longer. So, instead of just dropping the watch on the nightstand, take the little extra effort to let it rest on its dock. Boom. Fresh battery next morning ready to chew through the day.

Dorky looks maybe?

That smartwatches look ugly is the second most common mockery about them. But what can I say? The LG G Watch is just one of the many available smartwatches; if you don't like it, there are plenty other options to suit your taste. However, it is true that the smartwatches are still rather thick and, in general, bulky today—but this could be said of any new technology (remember the first cellphones? the first laptops?). Give smartwatch manufacturers a few years and, if the concept sticks, I am sure we will all see sleeker watches that rival the appearance of the fanciest analog watches.

But I'm not going to lie to you: it is true that the LG G Watch, in particular, is pretty big. In fact, it looks out of place on thin wrists. But, once again, that's a concern about a specific model and not about the product concept in general.

Watch and phone pairing

Android Wear relies on an Android smartphone, paired via a Bluetooth connection, for all of its Internet-based functionality. If the phone is off or out of reach, your watch is not able to do anything... other than tell you the time which, you know, is just fine considering that we are talking about a watch first and foremost here!

Now, when the watch is in reach of the phone, something interesting becomes available: the watch can be set up as a trusted Bluetooth device, so when the two are in reach, the phone will remain unlocked and not ask you for any PIN or pattern on wake-up. (Did you know you can do the same with your Bluetooth-enabled car?) While this is quite convenient, I have mixed feelings if only because my 2-year old daughter is now able to mess around with the phone at will.

Notifications: not so intrusive after all!

The most basic thing (after telling you the time) that an Android Wear watch will do for you is display the notifications you get on your phone no matter what app they come from—even if that app is not Wear-aware yet. You can dismiss these notifications trivially with a swipe-style gesture and you can interact with them to perform related actions. For example: if you get notified of an incoming WhatsApp message, you can either see the new text or scroll through the history of messages; or if you receive an incoming message, you can reply to it using voice dictation.

The deal breaker for me is being notified of incoming phone calls via the watch thanks to a smooth and very recognizable vibration pattern. I do not miss phone calls any more, and that's something certain family members (my wife, that is) are already happy about. (I'm known to not notice that my phone is ringing even when I am clearly hearing the sound and wondering aloud what it might be; true story, just happened this last weekend. Again.)

Control your phone

The way I generally see Android Wear at the moment is as a remote control for the phone. Notifications are just one aspect of it, but the watch can be used to command the phone to do a variety of things, including: opening a web search, starting the recording of an activity, taking a note, dialing a phone number, etc. The majority of these actions can be triggered both with touch or by voice, but some require voice interaction because the watch has no input mechanism for text.

The exciting part of this "remote control" functionality is that it can be extended by third-party apps. The Android Wear Face API provides the mechanism by which Android apps can expose extra functionality through the watch. The Strava app that I mentioned above is one clear example: the watch suddenly gains actions like "start a run" or "start a ride" and, when activated, the watch displays the current pace and lets you control the ongoing activity without having to touch the phone. Same goes, say, for Spotify, and probably for any other app in the next months to come.

Summing it up

All in all, I am positively surprised about these new smartwatches. This product is something I would have never bought for myself, and I confess I was skeptical about them at first. But I decided to give them a try with an open mind and it has already been over a month of continuous use with no intentions of leaving it behind. I like the watch: it has given me additional freedom from my phone and I am sure not to miss important phone calls any longer!

Give smartwatches the benefit of the doubt and, if you have the chance, use one for a few days. You may be positively surprised.

Thursday, November 20, 2014

Task tracking and the Bullet Journal

iGTD, Things, Org mode, OmniFocus, Google Tasks, Trello, Google Keep... All of them. All of them I have tried over the last few years and all of them have failed me in some way — or, rather, I have failed to adjust to their idiosyncrasies. Part of it is because the overwhelming feeling that builds up after days of continuous use due to how easy it is to end up with never-ending piles of open tasks.

In other words: even after making the effort to adjust to these systems, none of them have really worked for me. The one that kept me on track for the longest was Org mode, topping at three months of continuous use plus some more months of occasional use, which is nothing for a system that is supposed to help you plan your day, week, month, year and, well, life.

But about nine months ago, I made a discovery. I stumbled upon the Bullet Journal: a simple yet effective system to track tasks using traditional pen and paper. After watching the introductory video and giving the system a test drive for a week on an old notebook, I set out to invest a few extra dollars into a nicer journal:

Nice notebooks are "pricey," and that's why I bought one: the point of the exercise was to trick myself into using the shiny new purchase... and the trick worked for long enough to hook me into the system. Not surprisingly though: previous experiments of mine at tracking tasks with a simple and unstructured sheet of paper resulted in productivity boosts and a feeling of accomplishment that I did not get otherwise.

What is the Bullet Journal?

The Bullet Journal is an extremely simple notebook-based task-tracking system designed by Ryder Carroll. At its core is something called Rapid Logging, a set of trivial rules to record, in a chronological manner, tasks, notes, and events. The system adds some more structure to this by dividing the chronological list of items into days or topics, and by outlining a monthly spread and task management workflow.

It is interesting to see how such simple concepts can work so well in practice and, especially, how popular this system has become over the last couple of years. Just look at the Google+ community behind this methodology and the success of Ryder's Kickstarter project to see what I mean.

Monthly review: the best part of it

The monthly review is the part of the Bullet Journal system that I enjoy the most and the part that truly makes me feel the usefulness of the system. 9 months and 100 pages in and I can reflect and see that this system has made a positive difference in my work.

If you have ever read David Allen's Getting Things Done, you know that regular reviews are essential to ensure that the contents of your system are up-to-date and remain relevant. While it is easy (for me) to overlook this important thinking time with a computerized system, it is pretty much impossible to do so with a notebook system because of its linearity: when the next month arrives, the preparation of the new monthly spread triggers the review of the previous month.

That's, precisely, why I like it. According to the Bullet Journal guidelines, you should consolidate all of your pending tasks from the last month into a "carryover section" in the current month. Because the system is chronological and paper based, the implication is that this consolidation involves manually copying tasks from previous pages into the new month. Sounds burdensome? Exactly, and that's why this works so well: having to copy a task over will push you to decide whether the task is still relevant, whether the effort to do it at that point is lower than copying the task, or whether the task can be moved to the calendar because it now has a deterministic start/due date.

This consolidation step into a new monthly spread is also critical in keeping your journal manageable. Because all tasks are consolidated into a new month, you are left with a reduced set of pages to go through to locate open tasks. In my case, I only use about 10–15 pages per month, which means that this is the amount of pages I have to review on a daily or weekly basis to see where my projects are at.

My own tweaks: habits and weekly planning

Another great aspect of the Bullet Journal—or really, any journal—is that it is free form: if you don't like the rules, just come up with your own. To that extent, there are plenty of ideas online in places such as the aforementioned Google+ community, a multitude of blog posts, and at some point the new web-based portal that Ryder is working on.

Personally, I have adopted two tweaks inspired by what other people were doing.

The first is the incorporation of monthly and weekly goal-setting sections. These take the form of lists of coarse-grained tasks representing goals, and these lists serve as the basis from which to derive finer-grained tasks when planning the current day. These tasks representing goals cannot be easily accomplished, but that's by design: the idea is to use them to distill more specific "next actions" while at the same time having some kind of status record of your week and month.

The second is the tracking of habits. In my monthly spread, I reserve the right page to track a bunch of habits I want to build. I do so by matching up various columns to the calendar days and then just crossing out the tasks on the days when they are done. These include things like reading, cooking, shaving, or commuting by bike.

So far, I have only gotten so-so results from these two tweaks. Especially, the upfront planning that is necessary to make goal-setting work is a habit in itself that needs to be built, but an important one as plenty of productivity books will teach you. (See Decide by Steve McClatchy or The One Thing by Gary Keller.) When I spend time planning ahead, the following days are much more productive; however, without the ingrained habit, it very easy to get side-tracked and end up not doing any such planning.

The major drawback: future planning

The one thing I haven't really yet figured out is managing long-term planning with the Bullet Journal methodology.

An idea that comes to mind involves keeping individual pages to jot down project milestones and week-to-week expectations, but I'm not sure that would be easy to deal with: somehow I personally need the ability to visualize the timeline of the project on a calendar with all the time impediments that may exist. In this regard, I have been happy at work by depicting the available time as a collection of weeks and drafting the expected status of each project on those future weeks.

Also, the calendar spread proposed by the Bullet Journal is of limited value to me. I am very used to the online Google Calendar for timed appointments, and I am now abusing it to also mark tasks that need to be started at some point in the far future. For example, I now trust the Calendar system to remind me, five years from now, to renew my passport.

Again, the system is so free form that you can play with your own ideas on how to manage your tasks. Whatever suits best your workflow, go for it; and if that means combining the journal with an electronic system, so be it!

Summing it up

To this day, I am still surprised what a difference pen and paper has made on my productivity compared to computerized task tracking systems.

Sure, I sometimes miss the ability to access my system anytime, anywhere. But having a system that is always-on is useless if the system is forgotten. Carrying a notebook around has forced me to think about what I write in it and to want to look at it later on.

Give it a try. Do so by visiting the Bullet Journal website and watching the video.

Monday, November 17, 2014

shtk 1.6 is now available

The Shell Toolkit, or shtk for short, is a little project I introduced back in August of 2008 to support other tools such as sysbuild and sysupgrade. Since that time, the project has seen little activity because it did not have much to offer and because shtk's public interface was not documented (hence making it impossible for developers to get started with shtk).

Well, both are changing today with the brand-new release of shtk 1.6:

The first major change is the addition of manual pages to document the public API of shtk. After installation, type man 3 shtk to open the shtk(3) reference manual and dive straight into a comprehensive set of documentation. Pay special attention to the SEE ALSO sections and follow the links form there. Also note that there is an individual manual page for each public function offered by shtk so it's trivial to access the documentation from your favorite editor when you highlight a symbol name.

And why manual pages? Because shtk is designed to fit the minimalist user environment of a typical BSD system. The reason shtk exists in the first place is because such systems don't have any other high-level language available for scripting, yet scripting languages are ideal for system administration tools.

The second major change is the addition of a shiny-new unit-testing library, known as unittest, which I briefly described in a post to the shtk-discuss mailing list. This library is on-par, functionality-wise, with atf-sh. In fact, unittest is purely written in the shell scripting language thus avoiding the dependency on C++ that atf-sh has. Not to mention that the codebase is more modern and easier to extend.

If you have never used shtk before, I invite you to test-drive it now that we have fully-fledged documentation and some compelling functionality to offer!

Enjoy the ride.

Saturday, May 31, 2014

Code review culture meets FreeBSD

One of the things that often shocks new engineers at Google is the fact that every change to the source tree must be reviewed before commit. It is hard to internalize such a workflow if you have never been exposed to it, but given enough time —O(weeks) is my estimation—, the formal pre-commit code review process becomes a habit and, soon after, something you take for granted.

To me, code reviews have become invaluable and, actually, I feel "naked" when I work on open source projects where this process is not standard practice. This is especially the case when developing my own, 1-person projects, because there is nobody to bounce my code off for a quick sanity-check. Fortunately, this may not be the case any more in, at least, FreeBSD, and I am super-happy to see change happening.

A few individuals in the FreeBSD project have set up an instance of Phabricator, an open source code review system, that is reachable at and ready to be used by FreeBSD committers. Instructions and guidelines are in the new CodeReview wiki page.

To the FreeBSD committer:

Even if you are skeptical —I was, back when I joined Google in 2009— I'd like to strongly encourage you to test this workflow for any change you want to commit, be it a one-liner or a multipage patch. Don't be shy: get your code up there and encourage specific reviewers to comment the hell out of it. There is nothing to be ashamed of when (not if) your change receives dozens of comments! (But it is embarrassing to receive the comments post-commit, isn't it?)

Beware of the process though. There are several caveats to keep in mind if you want to keep your sanity and that's what started this post. My views on this are detailed below.

Note that the Phabricator setup for FreeBSD is experimental and has not yet been blessed by core. There is also no policy requiring reviews to be made via this tool nor reviews to be made at all. However, I'm hopeful that things may change given enough time.

Let's discuss code reviews per se.

Getting into the habits of the code review process, and not getting mad at it, takes time and a lot of patience. Having gone through thousands of code reviews and performed hundreds of them over the last 5 years, here come my own thoughts on this whole thing.

First of all, why go through the hassle?

Simply put: to get a second and fresh pair of eyes go over your change. Code reviews exist to give someone else a chance to catch bugs in your code; to question your implementation in places where things could be done differently; to make sure your design is easy to read and understand (because they will have to understand it to do a review!); and to point out style inconsistencies.

All of these are beneficial for any kind of patch, be it the seemingly-trivial one-line change to the implementation of a brand-new subsystem. Mind you: I've seen reviews of the former class receive comments that spotted major flaws in the apparently-trivial change being made.

The annoying "cool down" period

All articles out there providing advice on becoming a better writer seem to agree on one thing: you must step away from your composition after finishing the first draft, preferably for hours, before copyediting it. As it turns out, the exact same thing applies to code.

But it's hard to step aside from your code once it is building and running and all that is left for the world to witness your creation is to "commit" it to the tree. But you know what? In the vast majority of cases, nobody cares if you commit your change at that exact moment, or tomorrow, or the week after. It may be hard to hear this, but that pre-commit "high" that rushes you to submit your code is usually counterproductive and dangerous. (Been there, done that, and ended up having to fix the commit soon after for stupid reasons... countless times... and that is shameful.)

What amuses me the most are the times when I've been coding for one-two hours straight, cleaned up the code in preparation for submission, written some tests... only to take a bathroom break and realize, in less than five minutes, that the path I had been taking was completely flawed. Stepping aside helps and that's why obvious problems in the code magically manifest to you soon after you hit "commit", requiring a second immediate followup commit to correct them.

Where am I going with all this? Simple: an interesting side-effect of pre-commit reviews is that they force you to step aside from your code; they force you to cool down and thus they allow you to experience the benefits of the disconnect when you get back to your change later on.

Keep multiple reviews open at once

So cooling down may be great, but I hear you cry that it will slow down your development because you will be stuck waiting for approval on a dependent change.

First of all, ask yourself: are you intending to write crappy code in a rush or, alternatively, do you care about getting the code as close to perfect as possible? Because if you are in the former camp, you should probably change your attitude or avoid contributing to a project other people care about; and if you are in the latter camp, you will eventually understand that asking for a review and waiting for your reviewer to get back to you is a reasonable thing to do.

But it is true that code reviews slow you down unless you change your work habits. How? Keep multiple work paths open. Whenever you are waiting for a change to be reviewed, do something else: prepare a dependent commit; write documentation or a blog post; work on a different feature; work on a completely-separate project; etc. In my case at work, I often have 2-3 pending changes at various stages of the review process and 1-2 changes still in the works. It indeed takes some getting used to, but the increased quality of the resulting code pays off.

Learn to embrace comments

Experienced programmers that have not been exposed to a code review culture may get personally offended when their patches are returned to them with more than zero comments. You must understand that you are not perfect (you knew that) and that the comments are being made to ensure you produce the best change possible.

Your reviewers are not there to annoy you: they are there to ensure your code meets good quality standards, that no obvious (and not-so-obvious) bugs sneak in and that it can be easily read. Try to see it this way and accept the feedback. Remember: in a technical setting, reviewers comment on your ideas and code, not on you as a person — it is important to learn to distantiate yourself from your ideas so that you can objectively assess them.

I guarantee you that you will become a better programmer and team player if you learn to deal well with reviews even when it seems that every single line you touched receives a comment.

Selecting your reviewers

Ah... the tricky part of this whole thing, which is only made worse in the volunteer-based world of open source.

Some background first: because code reviews at Google are a prerequisite for code submission, you must always find a reviewer for your change. This is easy in small team-local projects, but with the very large codebase that we deal with, it not always is: the original authors of the code you are modifying, who usually are the best reviewers, may not be available any longer. FreeBSD also has a huge codebase, older than Google's, so the same problem exists. Ergo, how do you find the reviewer?

Your first choice, again, is to try and find the owner of the code you are modifying. The owner (or owners) may still be the original author if he is still around, but it can be anyone else that stepped in since to maintain that piece of code.

Finding an individual owner may not possible: maybe the code is abandoned; maybe it is actively used but no single individual can be considered the owner. This is unfortunate but is a reality in open source. So do you abandon the code review process?

Of course NOT! Get someone with relevant expertise in the change you are making to look at your code; maybe they won't be able to predict all of the consequences of the change, but their review is lightyears better than nothing. At work, I may "abuse" specific local teammates that I know are thorough in their assessment.

The last thing to consider when selecting your reviewers is: how picky are they? As you go through reviews, you will learn that some reviewers will nitpick every single detail (e.g. "missing dot at end of sentence", "add a blank line here") while others will only glance over the logic of the code and give you a quick approval. Do not actively avoid the former camp; in fact, try to get them involved when your primary reviewer is on the latter; otherwise, it's certain that you will commit trivial mistakes (if only typos). I'm in the nitpickers camp and proudly so, if you ask.

Should all of the above fail, leaving you without a reviewer: ask for volunteers! There will probably be someone ready to step in.

Set a deadline

Because most committers in open source projects are volunteers, you cannot send out a change for review and wait indefinitely until somebody looks. Unless you are forbidden to commit to a specific part of the tree without review, set a deadline for when you will submit the change even if there have been no reviews. After all, the pre-commit review workflow in FreeBSD is not enforced (yet?).

If you end up committing the change after the deadline without having received a review, make sure to mention so in the commit message and clearly open the door at fixing any issues post-commit.

Learn to say no

Because code reviews happen in the open, anybody is allowed to join the review of a patch and add comments. You should not see this as an annoyance but you must know when to say no and you must clearly know who your actual approvers are and who are just making "advisory" comments.

Also note that comments in a review are not always about pointing obviously-wrong stuff out. Many times, the comments will be in the form of questions asking why you did something in a specific way and not another. In those cases, the comment is intended to start a discussion, not to force you to change something immediately. And in very few cases, the discussion might degenerate in a back-and-forth against two very valid alternatives. If this happens... you'll either have to push your way through (not recommended) or find a neutral and experienced third reviewer that can break the deal.

Get to the reviews!

Wow, that was way longer than I thought. If you are interested in getting your code for FreeBSD reviewed — and who wouldn't be when we are building a production-quality OS? — read the CodeReview wiki page instructions and start today.

And if you have already started, mind to share your point of view? Any questions?