Juan Ibiapina

Ask When Uncertain

Fri, 09 Oct 2026 12:15:04 GMT

"Ask when uncertain". I've seen that in AI prompts.

I doubt that works. Of course one would have to measure to know if it works, but measure what? We could measure if it asked more questions. We could also use a set of benchmarks where we expect it to stop at an exact place.

But I wouldn't expect two different humans to act on uncertainty the same way, why would I expect two different models to act on uncertainty the same way? It just seems unreliable – too dependent on training.

How about instead we try to be precise in specifying outputs?

Explore three different options and weigh pros and cons in terms of <actual list of criteria>

That way we control the output. I expect three options. I expect pros and cons for each item in the list of criteria.

Interesting Articles

Su, J., & Cardie, C. (2026). Knowing but not showing: LLMs recognize ambiguity but rarely ask clarifying questions [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.25284

We find a clear gap between recognition and behavior: models often identify ambiguity when explicitly asked to judge it, yet in the QA setting they overwhelmingly default to direct answers.

Wang, W., Juluan, S., Ling, Z., Chan, Y.-K., Wang, C., Lee, C., Yuan, Y., Huang, J.-t., Jiao, W., & Lyu, M. R. (2025). Learning to ask: When LLM agents meet unclear instruction. In C. Christodoulopoulos, T. Chakraborty, C. Rose, & V. Peng (Eds.), Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing (pp. 21773–21784). Association for Computational Linguistics. https://doi.org/10.18653/v1/2025.emnlp-main.1104

We find that due to the next-token prediction training objective, LLM agents tend to arbitrarily generate the missed argument, which may lead to hallucinations and risks.

Xiong, M., Hu, Z., Lu, X., Li, Y., Fu, J., He, J., & Hooi, B. (2024). Can LLMs express their uncertainty? An empirical evaluation of confidence elicitation in LLMs. In The Twelfth International Conference on Learning Representations. https://proceedings.iclr.cc/paper_files/paper/2024/hash/6733cf15e10e2cd1d59af033c3bb8507-Abstract-Conference.html

LLMs, when verbalizing their confidence, tend to be overconfident, potentially imitating human patterns of expressing confidence.

Yang, D., Tsai, Y.-H. H., & Yamada, M. (2024). On verbalized confidence scores for LLMs [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2412.14737

Our results reveal that the reliability of these scores strongly depends on how the model is asked, but also that it is possible to extract well-calibrated confidence scores with certain prompt methods.

Zhang, M. J. Q., Knox, W. B., & Choi, E. (2025). Modeling future conversation turns to teach LLMs to ask clarifying questions. In The Thirteenth International Conference on Learning Representations. https://proceedings.iclr.cc/paper_files/paper/2025/hash/97e2df4bb8b2f1913657344a693166a2-Abstract-Conference.html

Existing LLMs often respond by presupposing a single interpretation of such ambiguous requests, frustrating users who intended a different interpretation.

A Beautiful Machine to Watch

Tue, 23 Jun 2026 00:00:00 GMT

When developing deltoids, I started with a problem I needed to solve. I wanted to see more context when reviewing code, and I wanted that context to be smart. Code is structured, but diffs only show a couple of lines before and after the change. I asked Claude to implement it, and the initial version was not well designed. You could call it vibe-slop, in the sense that I didn't properly design or review it.

As I used it, edge cases started to appear, and some were bad. Parts of the diff went missing. Some diffs got duplicated. Some showed up in the wrong order. All of these break the diff algorithm, and that's the last thing you want from a diff tool.

But here's a different way to look at it: Could I have sat down and developed an algorithm that solves this well? I don't think I could have. Before AI, I would have tried anyway. I would probably have written a basic version, maybe just as bad as the AI's, maybe a little better, who knows. But it would have taken a long, long time.

As the edge cases appeared, I wrote tests and fixed individual cases. Claude and I never redesigned a solution. Code quality went down. The more this happened, the more other things broke, until it got really hard to add anything at all. This is not specific to agents. This is just how coding works.

Now this code is a legacy system, and I love legacy systems. They hold all the knowledge you need to build something great. You only have to read the code and figure out what algorithm would actually cover all the cases. You have to generalize it. And in the process of covering those edge cases, asking Claude to fix them, and reviewing the code, I developed a feeling for the algorithm. What is that feeling if not experience grounded in years of software development? That's important to me: even working through Claude, I still get the feeling for the algorithm I am after.

Now I have tests, feedback, experience, and real usage data to check that the feeling is pointing in the right direction. I can feed all of that into Claude and design the algorithm along with it.

Is it going to be good enough? Probably good enough for all the cases we already have, and maybe better for future ones, since a generalization should hold up better for what's coming. Maybe new cases show up that it doesn't handle well. That is just how software works.

From my point of view, here's what happened: I imagined a diff tool that would give me better context and let me review code better. Then I built it with the tools I have. The tools I have now are better and faster than before. That's it.

What I love about programming is that I can take my imagination and make it tangible. Make it work. Make it move. Make it a machine that does things on its own. That's what software is to me, a machine that does things on its own, and it's beautiful to watch. I could always do that with code. Now I can do it a hundred times faster, and it's the same feeling.

Diffs for reviewing agentic code

Tue, 21 Apr 2026 00:00:00 GMT

I review a lot of AI generated code.

Here's what it looks like:

    line: &str,
    width: usize,
    scopes: &[HunkScopes],
    scope_expanded: bool, // [!code ++]
) -> Vec<Line<'static>> {
    if let Some(content) = line.strip_prefix('+').filter(|_| !line.starts_with("+++")) {
        return vec![syntax_diff_line(content, DIFF_ADDED_BG, &entry.path, width)];
    // ...
                .find(|s| s.hunk_new_start == new_start)
                .map(|s| s.ancestors.as_slice())
        });
        return render_hunk_separator(line, &entry.path, width, ancestors); // [!code --]
        return render_hunk_separator(line, &entry.path, width, ancestors, scope_expanded); // [!code ++]
    }

    vec![Line::from(Span::raw(fit_line(line, width)))]

What is even going on?

Try this version instead:

fn render_diff_line(
    entry: &HistoryEntry,
    line: &str,
    width: usize,
    scopes: &[HunkScopes],
    scope_expanded: bool, // [!code ++]
) -> Vec<Line<'static>> {
    if let Some(content) = line.strip_prefix('+').filter(|_| !line.starts_with("+++")) {
        return vec![syntax_diff_line(content, DIFF_ADDED_BG, &entry.path, width)];
    }
    if let Some(content) = line.strip_prefix('-').filter(|_| !line.starts_with("---")) {
        return vec![syntax_diff_line(
            content,
            DIFF_DELETED_BG,
            &entry.path,
            width,
        )];
    }
    if let Some(content) = line.strip_prefix(' ') {
        return vec![syntax_diff_line(content, Color::Reset, &entry.path, width)];
    }
    if line.starts_with("@@") {
        let ancestors = parse_hunk_new_start(line).and_then(|new_start| {
            scopes
                .iter()
                .find(|s| s.hunk_new_start == new_start)
                .map(|s| s.ancestors.as_slice())
        });
        return render_hunk_separator(line, &entry.path, width, ancestors); // [!code --]
        return render_hunk_separator(line, &entry.path, width, ancestors, scope_expanded); // [!code ++]
    }

    vec![Line::from(Span::raw(fit_line(line, width)))]
}

This shows the entire function, and it's easy to see what changed: a new scope_expanded argument is added to the signature and passed through to render_hunk_separator. Easy to see in this diff. It also shows the entire function, which allows me to keep learning about the codebase since I don't literally type the code anymore.

Here is another example:

    entry_indices: Vec<usize>,
    diff_scroll: usize,
    diff_cache: Option<DiffCache>,
    show_expanded: bool, // [!code ++]
}

    // ...
            entry_indices: vec![0; trace_count],
            diff_scroll: 0,
            diff_cache: None,
            show_expanded: true, // [!code ++]
        }
    }

You can see a field is added and initialized, but it doesn't even show to what. Here's what I want to see:

struct AppState {
    focus: Focus,
    trace_index: usize,
    entry_indices: Vec<usize>,
    diff_scroll: usize,
    diff_cache: Option<DiffCache>,
    show_expanded: bool, // [!code ++]
}

    fn new(trace_count: usize) -> Self {
        Self {
            focus: Focus::Entries,
            trace_index: 0,
            entry_indices: vec![0; trace_count],
            diff_scroll: 0,
            diff_cache: None,
            show_expanded: true, // [!code ++]
        }
    }

This is possible using git diff -W, which can then be easily piped into delta. There's also difftastic which uses tree-sitter for diffing but it's limited to controlling diff context by number of lines.

What if we build something?

Zen in Coding Agents

Sun, 19 Apr 2026 00:00:00 GMT

LLM output is a very useful set of random words.

My friend Kao Félix always says something like that.

Like all zen ideas, this one is hard to see.

LLM output looks like real talk. It triggers your deepest emotions and fears. It is incredibly useful.

But LLM output follows no philosophy, mental model, cultural norms, ethics, reason or even logic. It is a process. And it's a process that we don't fully understand. We don't even know if the process is, by its nature, understandable.

Agentic output contains all combined knowledge of humankind, but it's also nothing.

It doesn't get any more Zen than that.

The paper-first rule

Sat, 11 Apr 2026 00:00:00 GMT

With AI coding agents, it is very easy to jump straight into coding.

I can build a prototype, test a UI, throw together a mockup, start shaping an idea in minutes. It is also very fun to do that.

On top of that, I designed my dev environment to remove friction. I can jump into a project and start coding instantly. Tmux sessions persist. Neovim is always ready. Custom git scripts automate flows. I used to run multiple projects in parallel. I could use git worktrees before AI coding agents existed. I put a lot of effort into removing any friction for coding. It's very personal, but you can find about 10 years of optimizations in my dotfiles.

This does not work anymore.

Nothing changed with AI, but everything changed.

Now it is too easy to start a new project in the middle of another one, because I do not have to literally type the code. I can branch into a new idea with almost no cost. That means I start too many things and think less about each of them.

Is this the part where we complain that AI is ruining our attention spans?

No.

This is the part where I fix it.

Enter paper first.

Before producing any code or starting any new project, I must write about it by hand on paper.

Not in a note-taking app. Not in a scratch buffer. Not in a prompt.

On paper. With my hand like it's 1999 and The Matrix just came out. This could also be deliberate friction and slowing the fuck down.

This changed my mindset from one day to the next. I focus more. I feel less anxious. I write more. I sleep better. And I still do not have to literally type the code when the time comes.

We'll see what happens over the next few weeks. I expect I'll get generally better results. Maybe. Or, if you prefer, Alan Watts can tell it better.

Go paper first.

Anthropic banned me for trying to use Claude Max on pi

Wed, 08 Apr 2026 00:00:00 GMT

Today I got banned by Anthropic.

I was trying to use my Claude Max subscription on pi. Sorry :(

I felt so sad.

I wanted was to use pi with Opus 4.6. Yes, I could use the API instead, but I can't afford the cost for the amount of use I make.

Why didn't I just use Claude Code? It probably would have worked well. In fact, it probably would have worked better than pi, because I would not have spent countless hours customizing every minimal aspect of my setup.

But then, would it be worth it?

I am a computer scientist. I use and craft software that lives in the soul of the computer. I am in this for the craft. I love the journey: building, designing, learning, and interacting with machines. And now I can talk to it and IT TALKS BACK. That still feels like a dream.

Unfortunately I don't want to work with closed source software.

I customize my software.

My software is my craft.

My software is my life.

How can I share the code to my autonomous agent?

Fri, 27 Mar 2026 00:00:00 GMT

How can I share the code for my autonomous agent if I cannot recommend people to use it? In fact, I say do not use OpenClaw, do not use ZeroClaw, do not use any agent framework. And to be clear, I'm talking to my audience, which is often software developers with access to coding agents.

The reason is that almost every product that has come out in the last few months is just prompting. In fact, most products for the last few years have just been different ways to prompt. A few haven't, but most of them have. So for example, if you hear about OpenClaw and you learn that it memorizes things about you and it learns as you go, all you need to do is prompt your agent with that. You tell it, you should from now on memorize facts about me and learn as you go. There you go, you've replicated the entire framework.

This is a problem for me because on one hand, I'm a publisher of software. I want to publish software. Worst case, I want to publish prompts, but there's nothing to publish. For my audience specifically, I don't want to say, hey, here's my agent framework. It's one more framework among a hundred.

The code for my agent has hard-coded stuff. It's very specific to how I do things. Its memory is not just a general store that it reads and writes to. It's actually connected to my notes in a way that it understands how I think. I continue to edit these notes manually, which is part of the workflow.

A big part of this is that software is now customizable per person. The reason there are so many different agent frameworks is that everybody can build their own and they're slightly different. It's easier to build your own than to customize someone else's. It's easier to build your own from scratch than to take a generic framework and use it.

That said, the pi coding agent is amazing. Pi is the vim of coding agents.

Replicating the full macOS ABC Extended Keyboard with XKB

Thu, 05 Jun 2025 00:00:00 GMT

In the previous post I created a fix for some of the missing dead keys in the us(mac) layout I use on NixOS

Today I thought, why not simply replicate the entire layout?

A quick search (with ChatGPT) gave me this great resource with an entire spec for the ABC Extended layout.

It was only a matter of giving ChatGPT an example and telling it to convert everything to xkb. Here's the result, althought I haven't actually tested every single case:

default partial default alphanumeric_keys
xkb_symbols "extended" {
  name[Group1]= "ABC Extended (macOS)";

  key.type[group1]="FOUR_LEVEL";

  // Numbers row
  key <TLDE> { [ grave, asciitilde, dead_grave, dead_horn ] };
  key <AE01> { [ 1, exclam, exclamdown, U2044 ] };
  key <AE02> { [ 2, at, trademark, EuroSign ] };
  key <AE03> { [ 3, numbersign, sterling, U2039 ] };
  key <AE04> { [ 4, dollar, cent, U203A ] };
  key <AE05> { [ 5, percent, section, U2020 ] };
  key <AE06> { [ 6, asciicircum, dead_circumflex, U0302 ] };
  key <AE07> { [ 7, ampersand, paragraph, U2021 ] };
  key <AE08> { [ 8, asterisk, bullet, degree ] };
  key <AE09> { [ 9, parenleft, ordfeminine, periodcentered ] };
  key <AE10> { [ 0, parenright, masculine, U201A ] };
  key <AE11> { [ minus, underscore, endash, emdash ] };
  key <AE12> { [ equal, plus, notequal, plusminus ] };

  // QWERTY row
  key <AD01> { [ q, Q, oe, OE ] };
  key <AD02> { [ w, W, dead_abovedot, U0307 ] };
  key <AD03> { [ e, E, dead_acute, U0301 ] };
  key <AD04> { [ r, R, registered, permille ] };
  key <AD05> { [ t, T, thorn, THORN ] };
  key <AD06> { [ y, Y, yen, U030F ] };
  key <AD07> { [ u, U, dead_diaeresis, U0308 ] };
  key <AD08> { [ i, I, dead_horn, U031B ] };
  key <AD09> { [ o, O, Oslash, Oslash ] };
  key <AD10> { [ p, P, dead_belowcomma, U0326 ] };
  key <AD11> { [ bracketleft, braceleft, leftdoublequotemark, rightdoublequotemark ] };
  key <AD12> { [ bracketright, braceright, leftsinglequotemark, rightsinglequotemark ] };
  key <BKSL>  { [ backslash, bar, guillemotleft, guillemotright ] };

  // ASDF row
  key <AC01> { [ a, A, dead_macron, U0304 ] };
  key <AC02> { [ s, S, ssharp, U0311 ] };
  key <AC03> { [ d, D, eth, ETH ] };
  key <AC04> { [ f, F, function, U0330 ] };
  key <AC05> { [ g, G, copyright, U2038 ] };
  key <AC06> { [ h, H, dead_macronbelow, U0331 ] };
  key <AC07> { [ j, J, dead_doubleacute, U030B ] };
  key <AC08> { [ k, K, dead_abovering, U030A ] };
  key <AC09> { [ l, L, dead_stroke, U0335 ] };
  key <AC10> { [ semicolon, colon, ellipsis, U2116 ] };
  key <AC11> { [ apostrophe, quotedbl, ae, AE ] };

  // ZXCV row
  key <AB01> { [ z, Z, dead_hook, U0309 ] };
  key <AB02> { [ x, X, dead_belowdot, U0323 ] };
  key <AB03> { [ c, C, dead_cedilla, U0327 ] };
  key <AB04> { [ v, V, dead_caron, U030C ] };
  key <AB05> { [ b, B, dead_breve, U0306 ] };
  key <AB06> { [ n, N, dead_tilde, U0303 ] };
  key <AB07> { [ m, M, dead_ogonek, U0328 ] };
  key <AB08> { [ comma, less, lessthanequal, U201E ] };
  key <AB09> { [ period, greater, greaterthanequal, U0294 ] };
  key <AB10> { [ slash, question, division, questiondown ] };

  include "level3(ralt_switch)"
};

Mac ABC Extended layout on NixOS

Wed, 04 Jun 2025 00:00:00 GMT

I previously discovered I can now type ţ on macOS, but now I want to have my Linux layout match macOS ABC Extended so I can type with the same dead keys on both systems.

I already use the xkb_variant mac. It matches some of the dead keys like e, i, n and u which are great for Portuguese (é, â) and German (ü, ß):

input "type:keyboard" {
  xkb_model pc104
  xkb_layout us
  xkb_variant mac
  # lv3:lalt_switch makes the left Alt key a third-level chooser key (keyd remaps Start to be Alt)
  xkb_options "lv3:lalt_switch"
  repeat_delay 250
  repeat_rate 40
}

But as it turns out, option+c in this variant outputs ç, not a dead ,.

Let's fix it because who can live without ţ? ţac-pac!!

First we need a new layout that inherits from my current one us(mac) and simply overrides the one key we need, c (AB03).

default partial default alphanumeric_keys
xkb_symbols "extended-sequoia" {
  include "us(mac)"

  name[Group1]= "layout matching ABC extended on macos Sequoia";

  key <AB03> { [ c, C,  dead_cedilla, dead_cedilla ] };
};

Then we install it in NixOS with a configuration option:

services.xserver = {
  enable = true;

  xkb = {
    model = "pc104";
    layout = "abc";
    variant = "extended-sequoia";
    options = "terminate:ctrl_alt_bksp,lv3:lwin_switch";
    extraLayouts = {
      "abc" = {
        description = "ABC layout similar to macOS";
        languages = [ "eng" ];
        symbolsFile = ./symbols/abc.xkb;
      };
    };
  };
};

And in Sway config:

input "type:keyboard" {
  xkb_model pc104
  xkb_layout abc
  xkb_variant extended-sequoia
  # lv3:lalt_switch makes the left Alt key a third-level chooser key (keyd remaps Start to be Alt)
  xkb_options "lv3:lalt_switch"
  repeat_delay 250
  repeat_rate 40
}

There we go! Şåa-ţi c∫a m∫a f∫acåur∫am! OH NO. Some more fixes for macron and breve in Romanian:

default partial default alphanumeric_keys
xkb_symbols "extended-sequoia" {
  include "us(mac)"

  name[Group1]= "layout matching ABC extended on macos Sequoia";

  key <AC01> { [ a, A,  dead_macron , dead_macron  ] };

  key <AB03> { [ c, C,  dead_cedilla, dead_cedilla ] };
  key <AB05> { [ b, B,  dead_breve  , dead_breve   ] };
};

And now I have a place where I can fix any differences between keys on macOS and NixOS.

The final (and eventually probably updated) version can be found in my dotfiles

References

How to define new xkb layouts: https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts
Source code for us(mac) xkb_variant: https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config/-/blob/master/symbols/us#L730
Custom XKB layouts in NixOS Manual: https://nixos.org/manual/nixos/stable/#custom-xkb-layouts

I can now type z̧

Sun, 25 May 2025 00:00:00 GMT

I upgraded my MacBook (named macm1) to MacOS Whatever and it seems like the way you input cedilla in the ABC Extended keyboard has changed.

I think that pressing option+c used to output ç but now it's a dead key for ¸. A dead key means that the ¸ can be combined with other keys to generate combinations like: ņ, ẹ and of course ç.

You may ask: when would I ever need to type a combination like ¸ or ḩ?

Well, here it is, a blog post that needed it.

Also, my girlfriend is from Galați.

Blood on the Clocktower, software development and making life decisions

Mon, 28 Apr 2025 00:00:00 GMT

I played a game the other day called Blood on the Clocktower. It’s a social deduction game where a team of good townsfolk needs to kill a demon to win. It’s similar to other social deduction games like Secret Hitler or The Resistance.

One big difference is that Blood on the Clocktower has a storyteller who controls some aspects of the game. For example, the storyteller chooses what information each player receives, based on their character’s abilities and effects.

At one point during the game, my friend Sam — the storyteller — made a mistake. According to the rules, a certain ability should have proced, giving us some potentially false information (because the character was poisoned. But instead, the ability didn't proc at all. The fact that nothing happened was a clear sign that the character was poisoned — something that would have been much less obvious if the ability had proced as normal.

When I asked about it later, Sam said:

You have to make a choice and stick to it.

That mindset really stuck with me.

What I found striking was that Sam didn't have to double down on that decision. He could have admitted to a one-time mistake, restarted the game, or tried to patch it somehow. Instead, he accepted what had happened and committed to it.

Part of why that worked is the scope of the situation: at worst, we were only affecting one timeboxed game. But more importantly, Sam avoided the biggest danger — the mental load of second-guessing your own decisions. That load can be overwhelming. I've seen it happen to others, and I've felt it myself.

In software development, we fail fast, iterate quickly, timebox work and retrospect. We accept mistakes as part of the process and move forward.

What about life? What practices do we have to keep ourselves from being paralyzed by doubt and mistakes?

Installing shell scripts from Github with Basher

Wed, 05 Nov 2014 00:00:00 GMT

The problem

On my previous post about Basher I mentioned that one of its goals was to be able to install scripts directly from github with minimal manual intervention. During the last month, I had to make some changes to get closer to that goal.

The package.sh file contains package information like binaries, completions, dependencies etc. The problem with having a package descriptor is that I need to fork every repo I want to install and add the file (maybe pull request a change for the maintainer to add the file). There is nothing wrong with this apprach, and it is in fact what bpkg does. This is partly what allows them to have custom install scripts per package.

On the other hand, what I really wanted was to see a package on github, run a one liner and keep working.

Besides, sourcing the package.sh file was a silly security problem. In addition, I never felt really confortable with having two different formats for packages (basher and bpkg). The discussion evolved but not fast enough for me.

So I got rid of it.

Conventions to the rescue

Now, basher looks for a bin folder and links any files in there. If there is no bin folder, it links all executable files in the package root.

With this change, I've been very happy installing packages with one liners.

Working packages

sstephenson/bats Bash Automated Testing System
pote/gpm Go package manager
pote/gvp Go versioning packager
treyhunner/tmuxstart named tmux sessions
zsh-users/antigen plugin manager for zsh
bripkens/dock easy bootstrapper using docker

Kind of working packages

holman/spark it also links an extra test executable
hecticjeff/shoreman binary ends with '.sh'

Future work

I want to automatically remove the '.sh' from binaries. Also figure out how to install completions for packages.

A Package Manager For Shell Scripts

Wed, 20 Aug 2014 00:00:00 GMT

In this post I'll introduce basher, a package manager for shell scripts.

Motivation

I do some development using bash. Not a web server, or a json parser, because that's not the point of bash (although fun!), but there are many tasks that are actually faster to do in bash.

When you write a bash script, it is usually a single file. All you have to do is put it somewhere in your PATH and you're done. You can just keep using it and forget about it. Unless you have multiple machines.

For me, the main problem with this approach is the lack of version control. I tend to get lost easily during development if I don't have the checkpoints a VCS provides. I need to be able to go back and forth in time and experiment. With the script in a version controlled directory, I only need to link the bin somewhere in the PATH. I can also publish to github.

It is very difficult to write bash scripts and get it right the first time. You might forget a space before a ], or you might put an extra space after an =. Or you might forget some quotes. The solution I found to this problem is TDD, of course. There is a testing framework for bash called bats, and it makes testing bash scripts as easy as it gets.

On the other hand, now you have to install a third party bash script (bats itself is written in bash). It's not just a single file you can copy, but the creators of bats are cool enough to provide a simple, reliable and well made install.sh script that copies the binaries to the right place. Still, you have to clone the project and find out how to install it. Remember you might need sudo.

Bats is also on brew, so that's simpler if you're on osx. There is probably something packaged for linux too, but which distros? Older install instructions for bats told you to clone the repo to ~/.bats and add its bin directory to your path. That's how I had to do for a while. In the end, that was the most reliable approach that I could reproduce among all my machines.

I want to publish a couple of bash scripts myself, but I don't really want to maintain installation instructions for osx and a bunch of linux distros. I want to think of a bash script as a package for bash, just like ruby has gems.

I also want to go to github, find a script I like, install it with one line and use it. If one of my machines doesn't have that script, all I need to do is run that one line and get it. No messing with my PATH either.

Basher

So I wrote basher. With it installed, you can do this:

$ basher install basherpm/bats

There, bats is in your PATH ready to be used. Whatever OS.

The install command looks for a repository on github, clones it to a known location and links the binaries to a place in your PATH.

I can also list installed packages easily:

$ basher list

And uninstall (with completion support):

$ basher uninstall basherpm/bats

Or check for outdated packages:

$ basher outdated

Check the commands command for a full list. Try also basher help <command>.

Shell support

Basher needs to be available in your PATH, of course, but it also needs to add one entry to the PATH, where all binaries will be linked. It does this by hooking into the shell, similarly to what rbenv does. The biggest difference is that rbenv modifies the PATH on the fly, according to what ruby version should be used. Basher is simpler, because it needs only one location added to the PATH.

If you try running basher init -, you'll see what gets added to the shell. This code is generated on the fly, according to what shell you use. It supports bash, zsh (might support any POSIX compliant) and even fish (thanks to João Vortmann).

Packages

Basher packages are simply github repos that have a package.sh file. This file defines what binaries need to be linked when installing and any package dependencies.

There is also experimental support for package runtimes. It allows you to require juanibiapina/gg (given this package is installed) in order to make some functions available to your shell. This might change in the future, but I find it very promissing.

Why not bpkg ?

I was using basher for a while, but did not plan on releasing it, when bpkg came out. At that point basher was very simple, and bpkg seemed to offer much more. I tried using it, but decided to go back and release basher instead.

Bpkg uses a package.json file to define packages. I assumed it was the same format as npm packages, so I got really confused when I checked the documentation for package.json and found out bpkg implements it incorrectly. It turns out, it is a different format, just with the same name. There is some unfinished discussion going on on this issue. Overall, I find the choice of name and format confusing.

Bpkg also doesn't keep the package repos on your local machine. Instead, it clones the repo, installs the binaries then removes the repo. I wanted to have local copies of each repo.

Bpkg uses whatever install script is provided by the package. This allows a package to install itself however it wants, including man pages or whatever is needed. On the other hand, it makes it difficult for me to track what has been installed and where. I don't like installs without the corresponding uninstall, so basher does not provide support for custom install scripts. It would be interesting to add mechanisms for installing man pages, completions etc. That way, any package with a properly defined package.sh would be automatically installable and uninstallable.

Instead, basher keeps everything under ~/.basher. You can remove this directory and get rid of everything easily.

Bpkg has support for github releases. You can choose to install a specific version. It also has support for local or global installs, like npm. Basher lacks these features, but they can be added if the need comes. Pull requests are welcome.

Basher is thoroughly tested. I failed to make a pull request to bpkg because I lacked confidence.

Conclusion

This has solved many of my shell scripting problems. I can have version controlled scripts automatically linked to the PATH without any changes, I can install scripts from github. It works the same way on my osx, ubuntu and debian (might work anywhere, just need to test). I have one central location where I install scripts. I can easily check for new versions of scripts without checking one by one. I can see the changelog for each script (since I have the full repo cloned locally).

It also helps me develop scripts. Check basher new or basher new-command.

There is still much that can be done. Pull requests and feedback are very welcome.

Shadowing

Tue, 12 Nov 2013 00:00:00 GMT

In Ruby you can do this:

puts = 1
puts(puts)

What will it output? Let's follow simple evaluation rules:

Line 1 assigns 1 to the variable puts. Since puts is already defined, is is now shadowed in this scope.

Line 2 reads puts from the environment yielding 1, and tries to call it as a method. You would expect ruby to complain that 1 is not a method.

But what really happens?

It runs fine and it works. puts used as a variable will look up the variable and find 1. When it is used as a method it will look up the method and ignore the variable.

There are probably reasons for this, a logical reasoning that is a consequence of the evaluation rules for Ruby. Overall, I don't care.

When reading the line puts(puts) I have to do syntactic analysis to find the word puts two times. Then I have to do semantic analysis to find out that the first puts is a method and the second is a variable. Then I have to follow the lookup rules for these two different concepts up the chain of environments. It's even funnier if you write it like this: puts puts.

I am not a compiler. I'll say again what is one of the worst things you can force the readers of your code to do: Mental Mapping. I don't want to compile code and jump through several hoops in my head while trying to understand business logic.

Of course you should never be doing anything even close to this. You should be avoiding shadowing in general (except for very simple cases), you should not be exploiting any potentially obscure features of the language. Trying to go as far away from complications as you can.

And this is a silly example, right? You would never find code like this in production.

Sure.

def clear_some_cache(id, clear_other_cache = false)
  do_something
  clear_other_cache(id) if clear_other_cache
end

def clear_other_cache(id)
  do_the_other_thing
end

Ignoring the other major problems with this code for now, this is from production code. This code was written with shadowing and exploiting this semantics on purpose, not by accident.

Misleading Bad Code

Mon, 11 Nov 2013 00:00:00 GMT

Bad code gives me anxiety. Sometimes I even get physically sick. Subtle bad code is even worse.

The subconscious mind sees and processes lots of things we don't realize. It communicates it to us in weird ways. Feelings, anxiety, lack of patience are some examples that happen to me, but it's probably different for each person.

Let's look at very simple, unharming code. I have obfuscated the variables, but this is production code.

var numberOfUsers = 1, userIsUgly, someController, redefineEverything, t = true, r = someParameter

On the premise that less code is better, someone has compiled all variable definitions in one line. Why is this bad?

Let's apply the Single Responsibility Principle. That means: How many reasons to change does this line have?

This one line has at least six different reasons to change. When you need to spend a long time (seconds are a long time for the subconscious) reading one line with several responsibilities that might not even interest you at that moment, this process makes your subconscious go crazy. That alone might make me stand up from your computer and get a coffee.

Later one person refactored that code into this:

var numberOfUsers = 1, userIsUgly, someController,
    redefineEverything, t = true, r = someParameter

The line break. Since we're in 1986, the line break in the bad code was inserted to make the line easier to read. There is no other way to make it easier to read, right? So why not break the one conceptual line into two, and have the reader of the code make the effort to figure out these are in fact the same line?

Two lines that are in fact the same line. The one thing that points out that they are the same line is the comma in the end of line one. Also, this feature of arbitrarily breaking lines at random points varies by language and by symbol. Some things sometimes allow line breaks, other things sometimes don't. Imagine a powerful processor (again your subconscious) going through this idea every time you happen to glimpse over this line while trying to read code. Metaphorical subconscious suicide.

Also, not everyone has screens of the same size, or even the same editors, or even the same window sizes.

So why not this version?

var numberOfUsers = 1,
    userIsUgly,
    someController,
    redefineEverything,
    t = true,
    r = someParameter

All line breaks are now meaningful.

You're saving 3 chars on each line. At what cost? Mental Mapping.

You're making the reader of the code who is interested on the definition of someController look at line 3, then at line one (for the 'var' keyword), to see that this is a variable definition. When looking at line one there is the extra burden of removing the other var definition (numberOfUsers) from the current context (remember I'm talking about subconscious burdens).

Also in practice you can't search for var someController.

What about this?

var numberOfUsers = 1
var userIsUgly
var someController
var redefineEverything
var t = true
var r = someParameter

To the subconscious mind, this version might be the most scary. After writing this, it's easy to see you should do something about it, and might eventually fall back to one of the above. But so far, it highlights the problem the best, and it's the easier to refactor.

This version has six different lines that do different things. They define variables that are used in different places. If you're looking for one, you'll find it in one line. You can safely ignore the other lines. No unnecessary line breaks.

Arguebly better than all others, but scary anyway. This version points you to several bigger issues. This method is probably doing too many things and it should be refactored. These variable definitions should probably be moved closer to their usages (and you didn't do it because the method is such a mess that you can't easily find them, true story). To the experienced programmer, this code is all probably going to be gone after refactoring. There is a lot of work to come.

Now imagine that on your subconscious mind on a Monday morning. Or a Friday night. Whatever scares you most.

Point: It's very hard for your subconscious mind to deal with legacy code where code complexity and major design issues are hidden behind poorly compacted lines and bad refactoring. Undoing one mess reveals a bigger mess and that is frustrating and makes it hard to find the right direction to go.

Try one of those Chinese puzzles where you have to undo everything before you can solve it.

Single Responsibility Principle

Fri, 01 Nov 2013 00:00:00 GMT

A quick google search for single responsibility principle for me returns these top 5 results, all of which contain this saying in one way or another:

In this context, a responsibility is considered to be one reason to change.

On the other hand, you'll see people mostly talking about responsibilities as "things to do". As an example, check out this answer on StackOverflow which is great! but says:

A good way to think about it is the "single responsibility principle," which says that a class should be responsible for a single (or small number) of things.

I find this way of thinking misleading.

In the context of SRP, the word responsibility can not be used interchangeably with "do a thing". One responsibility is not doing one thing. The reason for this is the definition of thing, which overall, is not agreed upon.

A "thing" can vary from processor instructions to major business logic. If every person in the project has a different view on how much is one thing (which is very likely), there will never be an agreement on the sizes of classes, henceforth, on their responsibilities. It is simply not viable to have a discussion on how many things a method or class does.

Reasons to change, on the other hand, is much more practical. If there is more than one reason a class should change, break it in two. This is easy to apply to rails models, views and controllers, but we hardly do. It's common to write tested rails code that works and goes to production on the same day. It much more sensible, and rather difficult, realize that you're falling on a trap and need to refactor your code.

Here is a final note: For a second, forget your framework. Think about how you would do this with another framework. Think about how you would do this in a functional programming language. Consider this, get back and refactor so it reads better and is more easily maintainable.

Command line habits

Sun, 07 Oct 2012 00:00:00 GMT

Some time ago, my friend Duck wrote a very small shell script to check our command line habits. Here is my current version, after some modifications. It uses history from zsh, so you might need to change it if you're using bash (with contributions from Bruno Maioli and Serge Gebhardt):

alias habits='\history -500 -1 | sed "s/^[[:space:]]*[0-9]*[[:space:]]*//" | sort | uniq -c | sort -n -r | head -n 10'

This allows me to check what sorts of commands I usually type. I use this idea to find ways to make my programming environment more efficient. This is my current habits output:

     174 g s
      37 g a .
      21 g push
      21 g c
      14 guard
      14 g push heroku master
      11 r s
      11 g d
       9 vim
       6 g a -u .

g is just an alias for git, and most git commands I use are also aliased on my global config. r s (rails server), guard and vim are called automatically by tmuxinator when I want to switch projects.

Every time I check this output I learn something new about my habits. This time, I'm observing how much git is an integral part of my workflow, and how much time I spend checking statuses and diffs. It hints me to the need of some sort of visual representation of my working tree, but I still don't know what to do about that.

What I may want to do for the next alias version is to filter out git commands. They will be there anyway, so I might as well consider them 'pretty optimised' and move on to the next set. I suspect a bunch of rake related stuff will come up.