Software on Jose M.

HUMANS.md

Sun, 12 Apr 2026 21:00:50 +0200

Things got a bit messy.

They all demanded more, more and more: clients, your manager, deadlines coming up, even yourself, feeling you were falling behind, and now, thanks to AI, you can provide.

Oh boy, big time!

You don’t even execute the code anymore, reviewing PRs is almost a lost art, and you can’t remember the last time you typed some actual code in your editor.

You have reached peak productivity in this new world. You’ve even started experimenting with work trees, so you can put agents to work on multiple features and bugs at the same time.

But who has time to test things locally anymore? To understand the thousands of lines of code you’ve put in there in the last month alone? That’s when we need a new kind of file.

An understandable and self-updated file that tells me how things are organized in the code, how to run things manually, and which kind of technical direction we’re following with each change. That’s when we need humans.md.

This file is inspired by AGENTS.md or CLAUDE.md, which allows the LLMs to get the context of your project, but in a world where we don’t code anymore, perhaps we also need the opposite: a file to explain to us (humans) what’s going on at multiple levels. We could even instruct the coding agent to keep it updated while summarizing the important points.

P.S. This is a kind of joke at the moment, but I don’t think it’s too far into the future that we’ll see this file in some repositories.

If you don't write it, I don't read it

Tue, 07 Apr 2026 07:07:32 +0200

Writing might be repetitive, boring, and difficult. It takes effort, skill, and countless edits to make it right, to transform what you had in your mind into something people can understand without getting bored.

Now with AI, it’s very tempting to use Claude, or ChatGPT, to write something, or just use a dictation app because who wants to write anymore, right? But if you think that what you want to communicate is not worth the effort of sitting down and articulating it as a human being in writing form, perhaps it was not so important after all.

Writing is not only a dump of your thoughts, but it’s an exercise to organize your thinking, to articulate better what you had in your mind, to summarize some things, even to realize you were wrong sometimes.

Why would you think that if you didn’t take the time to write it, people will take the time to read it? Whenever I read something online and see some signals of AI-generated copy (like the infamous —), I skip it.

My rule is simple: if you don’t have time to write it, I don’t have time to read it.

Side Projects and AI

Mon, 01 Sep 2025 08:32:30 +0200

Photo by Remy Loz

Some years ago, building a side project meant finding time wherever you could. Late nights, weekends, or early mornings to squeeze in some work before your real job starts.

Any SaaS or app you wanted to build used to take months of this busy schedule until you could launch it. As a result, balancing building a side project with a day job (plus family!) was a challenge that few people were willing to accept.

Now, with tools like Claude Code, the paradigm has shifted. The cost of creating software is much cheaper. What used to take months now takes days. You can do most of your basic features with AI if you use a well-known framework with good standards. But what does this mean?

First, there is a natural big shift in our job market. With less effort to build software, everybody else is experiencing the same benefit, so we’ll need to hire fewer engineers to do the same job we were doing before. I already know great people who are facing hard challenges entering the job market as junior engineers.

If the barrier to launching a software product is lower, more will be in the market, making it harder to succeed. But at this point is where we, as software developers, are wrong; in fact it’s a great time to be an entrepreneur.

As a software developer, coding was never the real barrier to building a successful side business. Without AI, it might have taken longer, but we could still build what we wanted.

The real challenge was—and still is—everything else required to get paying customers. We love staying in our IDEs, shipping yet-one-more-feature to our grand total of zero users. It’s comfortable. It’s safe. It’s familiar.

What’s uncomfortable? Sales calls, cold emails, blog posts echoing in the void, facing rejection, or talking to potential customers (I know, scary!). These are the skills that turn code into revenue, and AI hasn’t fully automated them yet. So the challenges remain for everybody else, too.

The only difference is that now we get a faster feedback loop about the skills we lack to build a business. The sooner we recognize what’s actually holding us back, the sooner we can develop the skills that matter.

AI didn’t remove the obstacles—it just helped us find them faster.

From Simple to Ornate and Back Again

Wed, 07 Aug 2024 05:04:53 +0200

Art history shows us that we tend to move between adding “unnecessary” elaborate decorations to clean styles and back again. It’s almost an endless cycle repeated over and over.

This cycle happens in the different arts and other fields where design is involved, like software. Let’s trace it in architecture first.

Here is the Abbey Church of St James in Hungary (1206), a clear example of the Romanesque style. By its side, Notre Dame, completed in 1345. Take a moment to appreciate all the decorations in the second picture not present in the first one.

This tendency to add more details and decorations to an already functioning element of architecture went out of fashion (like it had done in previous periods). Here, you can compare Notre Dame with the Cathedral of Pienza, an example of Renaissance architecture.

So, 250 years to realize again that we don’t want to add so many grandiose elements and prefer simplicity?

If we move to Baroque and Rococo, it’s like going in the opposite direction again, adding more and more decorations that weren’t essential to the buildings. Here’s the Cathedral of Pienza compared to the Catherine Palace in Russia.

But after a while, we got tired and returned to simple and clear lines.

Thomas Jefferson Memorial in Washington, D.C

The cycle between this highly detailed and elaborate style and returning to simple and clean elements is not perfect. Art is a complicated combination of influence, technique available at the time, and the historical context in which it’s developed. However, the pattern is there.

The cycle is not only present in architecture. It can also be found in painting, photography, sculpting, literature, theatre, and even fashion. So it’s not surprising that we see it in software.

This is one of the first text editors: vi. It was created in 1978, and it is as simple as it gets visually. Although you need to learn a shortcut or two to use it :)

Here’s Microsoft Word, the king of text editors for a long time.

You could say it’s just the technology that didn’t allow developers to create something more visually appealing in the early 80s, and that’s partially right. But now, technology lets you do much more, and people are returning to this minimalism. Here’s iA Writer, a text editor for Mac I use to write these articles, and loved by many people.

You can find a similar tendency in Operating Systems like Mac OS. Here’s Mac OS X 10.0 (released in 2001).

2001 (source)

And we’re clearly back to clean interfaces in a recent version of Mac OS X 14.0, released 22 years later.

2023

Will We Go Back to “Rococo” Software?

I know it seems impossible now, but we’ll certainly will.

We naturally get tired of the same design styles over time, so we’ll get a new wave of overly designed software in the next few years. Given its reduced timeline compared to architecture or painting, software will take more time to see this cycle clearly, but it’ll be there.

That said, if we see software design as an independent visual art, it’s also possible that this change happens much more quickly, and what takes 100 years in architectural styles to change could take ten years in software. Only time will tell.

In the meantime, let’s enjoy this period of mostly simple software that focuses on doing one thing without distracting you.

The Beauty of Finished Software

Tue, 31 Oct 2023 08:32:49 +0200

Let me introduce you to WordStar 4.0, a popular word processor from the early 80s.

WordStar 4.0

As old as it seems, George R.R. Martin used it to write “A Song of Ice and Fire”.

Why would someone use such an old piece of software to write over 5,000 pages? I love how he puts it:

It does everything I want a word processing program to do and it doesn't do anything else. I don't want any help. I hate some of these modern systems where you type up a lowercase letter and it becomes a capital. I don't want a capital, if I'd wanted a capital, I would have typed the capital.George R.R. Martin

This program embodies the concept of finished software — a software you can use forever with no unneeded changes.

Finished software is software that’s not expected to change, and that’s a feature! You can rely on it to do some real work.

Once you get used to the software, once the software works for you, you don’t need to learn anything new; the interface will exactly be the same, and all your files will stay relevant. No migrations, no new payments, no new changes.

This kind of software can be created intentionally, with a compromise from the creators that they won’t bother you with things you don’t need, and only the absolutely necessary will change, like minor updates to make it compatible with new operating systems.

Sometimes, finished software happens accidentally; maybe the company behind it has disappeared, or the product has been abandoned.

There are also some great examples in the UNIX world of finished software: commands like cd(to change the current directory) or ls(to list what’s there) won’t ever change in a significant way. You can rely on them until the end of your career.

The seduction of constant updates

Our expectations for software are different from other products we use in our daily lives.

When we buy a physical product, we accept that it won’t change in its lifetime. We’ll use it until it wears off, and we replace it. We can rely on that product not evolving; the gas pedal in my car will always be in the same place.

However, when it comes to software, we usually have the ingrained expectations of perpetual updates. We believe that if software doesn’t evolve it’ll be boring, old and unusable. If we see an app with no updates in the last year, we think the creator might be dead.

We also expect new versions of any software will be better than the previous ones. Once it’s released, most of our problems will be solved! What a deceiving lie.

Sometimes, a software upgrade is a step backward: less usable, less stable, with new bugs. Even if it’s genuinely better, there’s the learning curve. You were efficient with the old version, but now your most used button is on the other side of the screen under a hidden menu.

Finished software is a good reminder

In a world where constant change is the norm, finished software provides a breath of fresh air. It’s a reminder that reliability, consistency, and user satisfaction can coexist in the realm of software development.

So the next time you find yourself yearning for the latest update, remember that sometimes, the best software is the one that doesn’t change at all.

References

[1] George R.R. Martin in Conan show (2014). https://www.youtube.com/watch?v=X5REM-3nWHg.

Good Code Is Invisible

Wed, 19 Feb 2020 14:08:51 +0100

We all try to create good and clean code, projects that are maintainable and easy to change and yet, we don’t appreciate when we have one.

Do you remember the last time you easily change something in your code?

Maybe it was a simple constant that was only in one place, or a new parameter in an API endpoint that was fast to test. You might remember but I bet you didn’t stop to appreciate how easy the change was, how productive it felt and how it could have been much worse in other scenarios, it just felt right. You didn’t think too much about it because good code is invisible.

We don’t think too much about existing code until it gets in our way to accomplish what we want, in the same way we don’t appreciate our own good health until we get ill.

Product’s perspective

From the stakeholders of a product, good and maintainable code is expected, although rare to find.

They treat code in the same way that I treat my car. When I get into my car and start the engine, I expect it to work well and get me safely to my destination. I’d not be very happy if I see a warning light complaining about something I didn’t know it existed and I’d be even more concerned if three of them are on in the same trip.

When you work with product stakeholders, they don’t pay attention to the code. They don’t care about how many returns or lines you have in a single method or whether you use TDD or modify the code in production with an FTP client.

They see the project as the final user is going to perceive it. They’re trying to get the project somewhere else and code can help or prevent that from happening. They care about results in the form of features, bugs or speed, things way more tangible that the code you see in the editor.

The fact that your code is good and maintainable is a competitive advantage that only you and your colleagues truly appreciate and, although it affects all the stakeholders of the product in a big way, they’re just usually not aware of it.

And with all of this, if it’s very likely that few people notice how easy is to work with that project, why should you care?

This is your life

First of all, because, as Dave Thomas and Andrew Hunt mention in “The Pragmatic Programmer”: “this is your life”. Do you want to have a fulfilling pride of your accomplishments every week? Do you want to look at that piece of code and easily see how you made it better? Or do you prefer to spend the rest of your days in that company or project barely surviving, sweeping dirty code under the carpet with the hope that it’ll get better magically someday because you’ll have time for the ultimate refactoring (or rewriting the whole thing)?

Common goals

Outside your personal feelings and goals, you’re working in that project because, deep down, you care about something. It could be the mission of the company, your team, the users or even just the money you’re making there. In any case, the better the project is because you cared about your work, the more chances it’ll have to succeed. And even if it doesn’t, you won’t have any regrets that it was your fault.

Bad code is like a disease

Bad code can hurt and eventually kill companies. If your company can’t adapt fast enough in a new market others will pass by and win. If your users aren’t happy about the quality of something you’ve built and you don’t know where the issue is because the code is a mess, you might lose them. If they leave others might follow and soon, what you cared about when you started in that project, might be lost forever.

Do what you can every day to stay healthy and treat your code in the same way, you won’t regret it.

Why I Keep a Personal Log of Bugs

Thu, 24 Oct 2019 15:08:51 +0100

Notebook

Photo by Negative Space

When creating software, you'll make mistakes. Sometimes they'll be huge, sometimes they'll be small but you can always learn from them if you spend some extra time documenting them.

After working for more 10 years as a software engineer I’ve realized it doesn’t change. You might develop some techniques to prevent some from happening but others will show up, it never ends.

In order to learn from those mistakes and try to avoid them in the future you can develop a bug log. We’ll see here what that is and how it works but I promise it helps.

I recently introduced this idea at Buffer where I’ve been working for almost 5 years now and I thought it’d be cool to share it publicly here as well.

The (endless) cycle of software development

1. Work on a new feature
2. Fix bug(s)
3. Go back to 1.

Sometimes you might focus on only developing new features or only fixing bugs but those are the biggest chunks of your work if you’re building software.

I think we focus a lot on the how to develop more effectively new features: using the latest framework, text editor or IDE, a new programming paradigm, etc. and when we build something new again, we try to apply the things we’ve learnt and improve.

On the other hand, when we fix a bug, we tend to do it as quick as possible and then move on to something else, almost like it didn’t happen in the first place. Very few people spend any time trying to learn new debugging techniques instead of learning the latest framework that came out.

If we spent more time reflecting on those errors, learning from them and understanding where they came from we could improve a lot.

Documenting a personal mistake

I’ve started to document those bugs, only the ones where I was the only engineer who did it so I can totally understand the context and reflect on what I personally did.

There are many different ways to do this, but I thought it’d be cool to have one place where I can gather all of them and search in the future for references and patterns. I don’t know if the term already exist but I called it the “bug log”. 🤷‍♂️ 😅

What’s a bug log?

A bug log is a collection of your past introduced bugs with different sections for each bug:

The context where the bug was introduced and what you were trying to achieve (fixing another bug, adding a new feature, etc).
Why the bug happened. What was wrong in production that made you realize that there was a bug.
How you fixed it.
The lesson you learned afterwards. A summary of what you’ve learned in the process.

These sections are the ones that work for me, but feel free to adapt them to your needs if you want to start a bug log.

An example of an entry in the bug log

# Context
When working on this JIRA ticket ____, trying to track an action on the backend,
I merged the pull request and it failed in production in a certain environment.

- Link to ticket: ....
- Link to pull request: ....

# Why the bug happened
The environment variable was not set in one of the environments and that caused
an error in production.

# How I fixed it.
I created the new environment variable by doing X and Y.

# Lesson learned.
When using an environment variable make sure it's available in all the environments
before deploying.

As you can see it’s not anything formal and it’s just for you so feel free to use the format and tone that makes the most sense.

The nice aspect about this is that if I see this becomes a pattern like if I introduced more than one bug of this type in the next year or so, I can work on a better solution. For example, a parser that compares the env. variables used in a new pull request with the ones that are in production.

Where do I store the bug log?

I’ve become a big fan of Notion and I’ve added it there so other team members can see it but it could be anywhere, any note-taking app or even a Github repo with some markdown files could work.

What to do with the “lesson learned” sections?

Something I’ve realized is that by summarizing in one sentence the bug I introduced and why I can easily reflect and learn the lesson. I’ve taken one extra step to not forget it for the future so I use Anki, a solution for reviewing cards from time to time, helping you learn what’s in the card.

I used it before for other purposes but I created a new collection for this. What I do is creating a card whose front is the situation I faced when I introduced the bug and the back is the lesson learned. For example, here it’d be:

Front
--------
What should I do when I use an environment variable in the code?

Back
--------
Check by doing X/Y if it's set in the right environments.

Here’s how it looks in Anki:

Anki Bug Log

This will reinforce my learning and it’s easier that I remember it in the future. It can also include some code samples so you associated the situation to new code that you’ll be modifying in the future.

I’m a big fan of Anki and how it can help you improve as an engineer so I’ll write an article about it soon.

Repeating past mistakes

The other thing I do is before filling a new entry, I can try to search in the log something similar. Sometimes that helps me understand if I tend to make the same kind of mistakes.

I hope this was useful to you! Do you have any thoughts or feedback? Let me know on Twitter! 😉

Introduction to Bitwise Operations

Wed, 09 Oct 2019 10:08:51 +0100

Bitwise operations are really useful and fast for storing and operate on certain values. They are way more used in systems where resources are more limited like video-games or embedded devices.

In this first article about bitwise operations, we get a quick introduction to them with a drawing (new format!) and some written content but I plan on sharing more 🙂.

What are bitwise operations?

They’re operations that deal with bits directly. Bits are 1s and 0s and it’s how everything is stored internally in a computer so being able to operate with them directly is very efficient because the processor is able to do those operations natively. Wikipedia says:

…typically, bitwise operations are substantially faster than division, several times faster than multiplication, and sometimes significantly faster than addition…

The three basic operators

There are more but let’s take a look today at the three most basic operators:

NOT

NOT is very simple, if there’s a 1 we get 0. If there’s a 0, we get 1.

It’s represented by ~ in most programming languages so for example: ~0101011 = 1010100.

AND

AND is like the boolean equivalent you already use in if conditions but with one difference, this operates at the level of bits:

1 & 1 = 1
1 & 0 = 0
0 & 1 = 0
0 & 0 = 0

OR

The same goes for the OR operation, represented with the | symbol in many programming languages.

1 | 1 = 1
1 | 0 = 1
0 | 1 = 1
0 | 0 = 0

How they operate with more than 1 bit

The key here is to remember that when we have a bitwise operation with more than 1 bit, we do it bit by bit. For example:

// Bitwise OR
111010
001100
-------
111110

Or in an AND operation:

// Bitwise AND
111010
001100
-------
001000

Example to show how to use them:

Intro to bitwise

Full drawing here

In a future article we'll see other operators because you can do some very efficient calculations with numbers but we need more than just these three. See you soon!

Remove Empty Elements in an Array in PHP

Tue, 01 Oct 2019 08:08:51 +0100

Problem with array_filter

This is a small trick to avoid issues when removing elements in PHP in an array.

If you have an array where some elements might be empty, like null, the first idea that comes to mind is doing something like this:

<?php
$array = ['a', null, 'b', 'c', null, 'd'];

array_filter($array, function($element) {
  return !empty($element);
});

Of, if we don’t provide a callback to array_filter, PHP will do the same for us:

<?php
array_filter($array);

This will give us a new array with all the empty elements removed. The problem though, is that the structure of the array in terms of indexes is not the expected one:

<?php
$array = ['a', null, 'b', 'c', null, 'd'];

print_r(array_filter($array));

// Array
// (
//     [0] => a
//     [2] => b
//     [3] => c
//     [5] => d
// )

So the indexes for the items that we skipped are gone. This could be ok but when we try to use that array in some situations like a query in the DB, we might find some issues.

In MongoDB for example, if you’re trying to do a find with $in, you’ll get an error if the array is missing some indexes.

Solution

The easiest solution to this problem of skipped indexes is to use array_values:

<?php
$array = ['a', null, 'b', 'c', null, 'd'];

$result = array_values(array_filter($array));

print_r($result);
// Array
// (
//     [0] => a
//     [1] => b
//     [2] => c
//     [3] => d
// )

(see it live)

This will extract the values into a new, well indexed, array.

CS Basics: How to refactor a boolean expression

Mon, 23 Sep 2019 08:08:51 +0100

Class

Photo by Pixabay

Computer Science sounds so boring, so academic, that sometimes it’s hard to know if there’s even any useful knowledge for our jobs building actual software.

Of course, I’m half joking. Computer Science is very important to understand what’s going on in a computer but I understand it doesn’t sound as attractive as learning a specific technology that’s in demand in the industry.

With this series of posts, I’ll try to extract from those long boring books a few things we can start applying right away and I hope you’ll find useful.

I’ll always start with the immediate practical part and then I’ll explain a bit more about the underlying reasons and terminology.

Let’s start today with some boolean expressions.

Why is it useful to refactor a boolean expression?

It has happened to me many times that, when refactoring a condition, I had to change it to create a method that makes sense in the class. Let’s show an simple example.

Imagine we have the following class (in Javascript, but can be applied to almost any language):

class Person {
  constructor(name, active, email = null) {
    this.name = name;
    this.active = active;
    this.email = email;
  }

  hasEmail() {
    return this.email !== null;
  }

  isActive() {
    return this.active;
  }

  sendEmail() {
    if (!this.isActive() || !this.hasEmail()) {
      return false;
    }
    // ... send email ...
  }
}

At some point we realize that it might be easier to have an internal method that can tell us if the user can receive emails. According to the code that’d mean that it’s an active user and has an email set.

We could do this:

  canReceiveEmail() {
    return ; // What do we return here? 🤔
  }

  sendEmail() {
    if (!this.canReceiveEmail()) {
      return false;
    }
    // ...
  }

As you can see the sendEmail method is more readable now, but what should we put in the canReceiveEmail() method?

I’ll let you think for a second…🙂

🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔

🤔🤔🤔🤔🤔🤔🤔🤨🐶🤨🤔🤔🤔🤔🤔🤔🤔🤔

🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔🤔

Did you figure it out?

What we need is the opposite value of the condition we had:

!this.isActive() || !this.hasEmail();

The negation of that expression would be:

this.isActive() && this.hasEmail();

I think intuitively we can understand that if what we were looking for is that:

The user is not active OR doesn’t have email;

The opposite would be that:

The user is active AND has email.

So the final class would look like this:

class Person {
  constructor(name, active, email = null) {
    this.name = name;
    this.active = active;
    this.email = email;
  }

  hasEmail() {
    return this.email !== null;
  }

  isActive() {
    return this.active;
  }

  canReceiveEmail() {
    return this.isActive() && this.hasEmail();
  }

  sendEmail() {
    if (!this.canReceiveEmail()) { // Notice negation of the method with !
      return false;
    }
    // ... send email ...
  }
}

(see in JSbin)

We could also have created the negative version cannotReceiveEmail() but I prefer to use “positive” method names since they tend to be more useful in other places of the code. Nevertheless, If we had done that the result would have been:

cannotReceiveEmail() {
 return !(this.isActive() && this.hasEmail());
}

sendEmail() {
 if (this.cannotReceiveEmail()) {
   return false;
 }
 // ... send email ...
}

Computer Science behind solution

What you just saw wasn’t discovered recently, the mathematician who formulated this solution, Augustus De Morgan, died in 1871.

This rule, along with another one we’ll see in a bit, are called “De Morgan’s Laws”. They’re part of a bigger field in Mathematics and studied in any computer science course, called Boolean Algebra.

The other rule is as follows. If we have this expression:

const willDieSoon = !this.isYoung && !this.worksOut

It’s equivalent to:

const willDieSoon = !(this.isYoung || this.worksOut)

If you didn’t get this one, think about what would happen in all the potential conditions:

Consider isYoung is true/false and worksOut is true/false. What would be the result of the expression? Wouldn’t that be the same that in the first case?

To truly understand this, it’s often useful to create a small table of possibilities. The last column represents: willDieSoon.

`isYoung`	`worksOut`	`isYoung OR worksOut`	`!(isYoung OR worksOut)`
false	false	false	true
true	false	true	false
false	true	true	false
true	true	true	false

The same table can be applied to the first expression:

`isYoung`	`worksOut`	`!isYoung AND !worksOut`
false	false	true
true	false	false
false	true	false
true	true	false

The Morgan’s Laws

So the two rules, written in a formal manner, would be:

$ \neg (P\lor Q)\iff (\neg P)\land (\neg Q) $

$ \neg (P\land Q)\iff (\neg P)\lor (\neg Q) $

$ \neg $ means negation. In Javascript and many other languages is !
$ \land $ means AND. In Javascript: &&
$ \lor $ means OR. In Javascript: ||
$ \iff $ means, without going too much into the details, that both expressions can be replaced with each other, that is, that both expressions are equivalent.

So in Javascript, we could say this is:

!(P || Q) == !P && !Q

!(P && Q) == !P || !Q

We’ve used the second one to refactor our code.

We started with the !P || !Q and ended with !(P && Q). Let’s review it now:

// we started with this condition to check before sending the email:
!this.isActive() || !this.hasEmail()

// Then, we moved the logic to canReceiveEmail()
this.isActive() && this.hasEmail()

// And used the negation of that:
!this.isActive() || !this.hasEmail() == !(this.canReceiveEmail())

// Which is:
!this.isActive() || !this.hasEmail() == !(this.isActive() && this.hasEmail());

// So:
!P || !Q == !(P && B)

Other Boolean Algebra Laws

If you didn’t know about this boolean algebra laws specifically, don’t worry! You’re probably applying others like:

$ x \lor y = y \lor x $

$ x \land y = y \land x $

Those mean that:

(weAreInChrome() || weAreInFirefox()) === (weAreInFirefox() || weAreInChrome())

(isRaining() && isCloudy()) === (isCloudy() && isRaining())

So, intuitively perhaps, you know that the boolean conditions with two values can be switched in order and the result is the same (🤓🗯️ that’s commutativity!).

There are many others boolean laws that are useful so I might do a second part of boolean logic later in the series with the ones that are not so intuitive.

Did you find this one useful? Let me know on Twitter please! 👋 🙂

References

Better Console Debug in Javascript

Sun, 15 Sep 2019 22:56:23 -0700

When debugging an object in Javascript, you usually do something like:

console.log(myObject);

Or even:

console.debug(myObject);

If we create the object with:

myObject = {
    name: 'test',
    size: 1234,
}

And you do a console.debug from somewhere in the code, in the console you’ll see:

So it might not be clear which object you’re dealing with. To solve this you can do:

console.debug({myObject});

The result is the name of the object and the full object printed:

This comes from ES6, it’s usually called shorthand property names and it works because the key and the object variable has the same name.

It’s the same thing that saying:

console.debug({myObject: myObject});

But more convenient as you can see. 😉

Useful Utilities in Unix for Developers

Fri, 13 Jun 2014 00:00:00 +0000

After some years working as a software developer in different companies I have used many programs and utilities in *nix environments that I’d like to share.

This is not an exhaustive tutorial about how to get the most of them, many options will be just ignored and I will list only how I use them on a daily basis.

Text processing

I use these utilities to get info from a log or to quickly change a config file on a server.

tail

It prints the last part of a file, it accepts some parameters like -f which will print the last part of a file and waits to print what it’s appended to the file (useful to see live logs).

$ tail -f logs/log.txt

Or if you want just the last n lines you can do:

$ tail -n 200 logs/log.txt

Further reading: Manual Page

grep

The grep command searches a file, the standard input or multiple files for a pattern and prints the lines that match that pattern. As a pattern you can use a string or a regular expression, here are some examples.

$ grep error logs/log.txt # searchs error in log

The same result using the standard input with a pipe:

$ cat logs/log.txt | grep error # searchs error in log

If you want to search only for the whole word, not including parts of it in the results you can with -w:

$ grep -w "error" logs/log.txt

In order to find a text in a tree of files you can use -r:

$ grep -r "error" logs

If you want to show the number of lines that match that pattern:

$ grep -c "error" logs/log.txt

Further reading: Manual Page

diff

Compares two files, I tend to use it without options.

$ diff file1.txt file2.txt

Further reading: Manual Page

vi

Well I could say many things about this editor. In my computer I use Vim on a daily basis but in many servers this is not installed by default where vi is so I use the later for small edits in config files.

$ vi nginx.conf

Network

curl

Allows you to transfer data with many protocols (HTTP, FTP…etc). I tend to use it to download something from the Internet.

$ curl http://example.com/file.zip

You can also use patterns like:

$ curl http://example.com/[2000-2014]/part{a,b,c}.zip

Further reading: Manual Page

scp

It’s like the combination of SSH and cp (altough it actually stands for secure copy), basically you can copy files through the SSH protocol, a simple example:

$ scp user@1.1.1.1:/files/1.txt .

It also works the other way around:

$ scp 1.txt user@1.1.1.1:/files/

Further reading: Manual Page

rsync

Rsync it’s a very complete tool but I tend to use like a simple “Dropbox” for certain directories.

Totally worth it to read the whole man page: http://ss64.com/bash/rsync.html.

Management

htop

An interactive process viewer, it’s like an improved top. You just need to execute htop and it will start. It isn’t installed by default in many distributions but it’s a common package. If you can’t install it you can use top, which is very similar.

Screenshot of htop

Further reading: Manual Page

iostat

Useful to monitor devices. It comes in handy when you don’t know what’s happening with a certain disk.

Screenshot of iostat on a Mac

Further reading: Manual Page

##Directories & Files

A lot in Unix systems has to do with files in some OS like Plan9 you can even treat a network interface as a file. These utilities are very basic but I could not leave them out.

mv / cd / cp / ls

Very basic utilities to move files or directories, change current directory, copy files or directories and list the content of a certain directory respectively.

pwd

Response to the question: where am I?

rm

Remove a file or tree of directories (with -r option).

ln

Link between two files or directories.

$ ln -f origin new_link

Further reading: Manual Page

find

I use it to find a file by name on a server:

$ find / -name foo

Further reading: Manual Page

Best utility: man

I remember that in my first class of OSs the teacher taught us the man utility. With man you can find everything you need, here you can see how to use it.

"Class Methods" in Scala

Mon, 15 Jul 2013 00:00:00 +0000

In Scala you can’t declare class methods, all the methods defined in a class belong to the object.

class House(val street:String) {
  def clean() {
    println("Cleaning!")
  }
}

val h = new House("5th")
h.clean
// Cleaning!

If we want a class method so we can do something like House.cleanAll we have to declare a companion object, which is basically an object with the same name of a previously defined Class:

object House {
  def cleanAll() {
    println("Cleaning all!")
  }
}

House.cleanAll

And now we have the methods of the objects defined in the class and the “class methods” defined in the companion object, kind of tricky but this is how it works in Scala.

Switch in Scala (Pattern Matching)

Wed, 10 Jul 2013 00:00:00 +0000

Scala has a powerful pattern matching mechanism, that we can think of a kind of “switch” if we come from another programming language, but it’s much more powerful and I’d love to explore some of its options here. A simple switch in Scala would look like this:

a match {
  case 1 => "One"
  case 2 => "Two"
  case _ => "Whatever"
}

In this case we have cases with 1 and 2, and if something else is matched then we return “Whatever”. But this is really simple, let’s make it more complex matching with types too.

a match {
  case i: Int => "Integer!"
  case s: String => "String: " + s
  case _ => "Whatever"
}

The above piece of code would look like this in Java:

if (a instanceOf Integer) return "Integer!";
if (a instanceOf String) return "String: " + s;
return "Whatever";

Now if a is a string we return “String”, if it’s an integer we return “Integer!” and if it’s something else we return “Whatever”.

We can also match against case classes. Imagine we have a case class with an integer and a string called Element.

case class Element(weight: Int, name: String)

In that case we can make a more complete match:

Element(85, "Fruit") match {
  case Element(_, "Fruit") => "Fruit is coming"
  case Element(80, _) => "80 kg!"
  case Element(80, "Fruit") => "80 kg of Fruit"
  case _ => "Whatever"
}

Apart from all the options described here we can add a boolean before the =>

Element(85, "Fruit") match {
  case Element(weight, "Fruit") if weight > 50 => "More than 50kg of fruit"
  case Element(80, _) => "80 kg!"
  case _ => "Whatever"
}

The nice thing about pattern matching is that you can use exactly the same structures in closures or catch blocks.

SBT in Scala Compile when You Save a File

Mon, 08 Jul 2013 00:00:00 +0000

I’ve worked on some Scala projects recently using SBT (Scala Building Tool) and every time I had a change in a file I needed to go to SBT and type compile until I found a simple instruction to keep it compiling for me. Just execute SBT and run the following command:

~ compile

Now every time you save a file it will be compiled automatically. In the official documentation you can see more details.

Set Content Type in RSpec

Tue, 11 Jun 2013 00:00:00 +0000

The last week I had a spec with a request where I needed to specify the content type and Google sensei didn’t help me.

It took me an hour until I finally found it, so let me show here briefly how to do it just in case I have to find it again.

it 'sets the content type' do
  post 'http://example.com', nil, {'CONTENT_TYPE' => 'application/json'}
  expect(request.content_type).to eq 'application/json'
end

The fact that the content type must be set with an underscore is counterintuitive since the RFC says otherwise.

Bruno: Localizable.strings to strings.xml (iOS - Android)

Sun, 19 May 2013 00:00:00 +0000

I’ve created a small gem, Bruno, to convert a Localizable.strings (iOS) file to a strings XML file (Android) and vice-versa.

To install it:

$ gem install bruno

A Localizable.strings file in an iOS project looks like this:

"APP_NAME" = "Test App";
"TITLE_ACTIVITY_MAIN" = "Test";
"INFO_TITLE" = "Information";
"INFO_SUBTITLE" = "More information";

And with a single command:

$ bruno convert --in Localizable.strings --out strings.xml

You will get this file:

<?xml version="1.0" encoding="UTF-8"?>
<resources>
  <string name="APP_NAME">Test App</string>;
  <string name="TITLE_ACTIVITY_MAIN">;Test</string>;
  <string name="INFO_TITLE">;Information</string>;
  <string name="INFO_SUBTITLE">;More information</string>;
</resources>;

You can use a strings XML file from Android to convert it to iOS too:

$ bruno convert --in strings.xml --out Localizable.strings

You can find the Git repository here: https://github.com/josem/bruno with further instructions.

Dynamic Conditions for Associations in Rails 3

Wed, 06 Feb 2013 00:00:00 +0000

If you are using dynamic conditions in Rails 3, like Time.now or 1.week.ago you should use a Proc for that condition.

Here’s an example:

has_many :rented_cars ...,
         :conditions => proc { "'#{Date.today.to_s(:db)}' <= end_rent_date" }

This way, Date.today will be called every time you perform a query.

If you would have done it like in the following example, there will be cases when the results you’ll get are not expected since the condition will have the day you started the Rails application and Date.today won’t be called again.

has_many :rented_cars ...,
         :conditions => ["'#{Date.today.to_s(:db)}' <= end_rent_date"]

(Link to Proc docs in Ruby).

Rescue from MultiJson::DecodeError in Ruby on Rails

Thu, 17 Jan 2013 00:00:00 +0000

If you are developing an API with Rails you need to rescue from the errors produced by a bad formatted JSON. In order to do that I use a middleware file placed in app/middleware named ParamsParserRescue.rb.

class ParamsParserRescue < ActionDispatch::ParamsParser
  def call(env)
    begin
      super(env)
    rescue MultiJson::DecodeError
      [400, {}, ["Bad Request"]]
    end
  end
end

And with this middleware file you need to tell Rails that should use it. In the configuration file application.rb add:

config.middleware.swap ActionDispatch::ParamsParser, "ParamsParserRescue"

Basically, we are doing whatever the call method does in ActionDispatch::ParamsParser and if the MultiJson::DecodeError exception is raised then we return a 400 HTTP Code instead of crashing.

Programming Challenges

Tue, 08 Jan 2013 00:00:00 +0000

I’d like to share some sites with programming challenges, also known as programming puzzles. I find them very useful to learn a new language, much more than reading a lot of books. Actually, I usually read one book for beginners of the language and after that I go to one of the following sites and start to code. My favourite is /r/dailyprogrammer.

/r/DailyProgrammer. Subreddit with three challenges every week or so (easy, intermediate and hard).
Project Euler. Math problems, created to be solved with a program.
Code Forces. More problems!
Code Golf. Part of the Stack Exchange platform. Very focus on the number of lines, but that makes it more fun.
Coding Bat. Most of the problems here are easy, and some of them include the solutions.
/r/ProgrammingChallenges. Another subreddit, less organized.
Extra: a post with more links to challenges.

Enjoy!

Creating a Great RESTful API

Wed, 26 Dec 2012 00:00:00 +0000

REST is a style of software architecture, often used in web. The design of Rails, for instance, is based a lot on REST. The idea behind this architecture is to have very similar interfaces to access all the resources in your system.

Recently I had to create 2 APIs in 3 months so I had to learn all I could in a very short time. I’d like to share some conclusions but giving the fact that to develop an API people usually say you need 10 years of experience take them with caution.

Use versions

People will trust your API so if you change something in the architecture of your application the 3rd party clients shouldn’t be affected by that.

The common approach here is to add a parameter to your URL, something like:

http://myapp.com/api/v1/

Or:

http://myapp.com/api/1/

I personally prefer the first method since is more clear, Google uses that too.

Use proper HTTP methods

GET: To get a resource or resources of one type.
POST: To create a new resource if you don’t know where it’s going to be.
PUT: To update a resource
DELETE: To remove a resource.

Consistent structure of URLs

If you don’t have a very simple system, probably you’ll end up with a lot of URLs so it’s important to respect a pattern, I used this one:

GET http://example.com/api/cars. To get a list of the resources of one type (cars, for example).
GET http://example.com/api/cars/1. To get a resource with the id 2.
POST http://example.com/api/cars. To create a new resource.
PUT http://example.com/api/cars/1. To update the resource with id 1.
DELETE http://example.com/api/cars/1. To remove the resource with id 1.

Security

I haven’t used the best avaliable method: OAuth. In my case with a token parameter and SSL was enough, but in your case it might not be.

Show examples

There will be a lot of users with a lot of different systems so it would be great if you can provide copy&paste examples. Probably curl will be enough for everyone.

Follow the leaders

Also known as Twitter, Google and Facebook engineers are probably smarter than you. To create my APIs I have ~~copied~~ studied the following APIs:

Some References I used to learn

Subversion and Files With @

Fri, 07 Dec 2012 07:30:40 +0100

If you have worked with Subversion and iOS you are probably aware of this problem. Whenever you are going to do something with a file that has an at sign in its name you can’t. For instance imagine you’ve just added a file for retina and try to add it to the repository (XCode can do this too):

$ svn add logo@2x.png

The message from Subversion will be:

Skipped logo@2x.png

That’s because Subversion uses the @ for other purposes.

From the Subversion book:

…how does svn know whether news@11 is the name of a directory in my tree or just a syntax for “revision 11 of news”? Thankfully, while svn will always assume the latter, there is a trivial workaround…

The workaround is as simple as adding an at sign to the end of the path:

$ svn add logo@2x.png@

Learning Vim - Introduction

Tue, 20 Nov 2012 00:00:00 +0000

I’ve started the great journal of learning Vim. I’ve heard a lot of good things about this editor and I’d like to learn how to use it effectively and share here all the things I’ll learn and my thoughts about every step of the way.

As a novice I’ll make a lot of mistakes but I’ll try to search all the commands and tips to make sure they will be accurate enough to be shared.

Learning Curve

It’s probable you’ve heard that Vim is hard, that, in order to generate a random string you just need to put a student in front of this editor and tell him to close it. Here you can see a slide with the learning curve of different editors:

Learning curves of different editors

Yes, Vim is scary right? But the truth is you can use Vim almost as any other editor until you learn the most basic commands and concepts that will make a good vim user. If you’ve using Vim for 20 years and you see me using vim the first weeks doing things like grabbing the mouse or using the arrow keys you could be surprised but the truth is you don’t need to use the most efficient way to do things all the time.

Resources

One of the main reasons so many people use Vim is its great community, which means a lot of good resources to learn too. In my case I’ll be following the great videos of Derek Wyatt and of course my dear friend Google.

I am looking forward to sharing all the things I’ll learn, stay tuned!

Naming of Predicate Methods

Wed, 07 Nov 2012 00:00:00 +0000

A predicate method is tipically one that should return a boolean value (true or false). These methods are useful in a lot of scenarios, like when you have an class with a boolean attribute.

Naming these kind of methods depends on the language you are using, but here are my top priorities.

Question mark

If you are using Ruby you can name it with a question mark at the end, which makes the code really readable. Something like this:

def is_alive?
  @alive
end

Question style

In some languages you can’t use a question mark in the name of a method, so I usually name it like this:

public Boolean isAlive {
  return alive;
}

Simple Getter

The worst name here, in my opinion, is having a get, like any other getter. It’s much better to have something like:

zombie.isAlive?

Rather than:

zombie.getAlive

Conclusion

Naming is so debatable that it would be silly to think more about this problem. I think with experience you can see the pros and cons of every option, I could even change my mind in some months about this :)

Too Short Routines?

Wed, 03 Oct 2012 00:00:00 +0000

I think as developers we tend to create complexity if we don’t think carefully about every line of code we are typing. Systems tend to be complex and managing that complexity is one of the main task we have.

Routines are great, they are one of the best ways to encapsulate algorithms and make your code more readable. Sometimes we think routines are too short, but actually the usually are too long. Reading Clean Code I realized Uncle Bob creates very short routines and all of them have a meaningful name.

Correlation between length of a routine and its name

Usually the longer a routine is the harder is to name it. When you do something like this:

for (var i=0;i<array.length;i++) {
  show(i);
}

It’s very easy to come up with a name like showAllElements(array). But if you are processing a lot of input parameters (like in a web service) and cleaning the input a good name will be harder to find.

Apart from that with small routines you’ll find your bugs easier and the reuse of that little algorithm is more likable since it’s already encapsulated and ready to be used again.

In the book Code Complete a lot of studies are shown without a clear conclusion but when the author is listing all the valid reasons to create a routine you get the idea that most small routines can achieve that. These are some of them:

Reduce complexity
Make a section of code readable
Improve portability
Simplify complicated boolean tests

Exceptions

Steve Mcconnell says in Code Complete that to ensure all routines are small is not a valid reason to create a routine:

In fact, some jobs are performed better in a single large routine.

Conclusion

In my experience, most of the time you can improve the readability of your code by creating smaller routines. To finish let me show you the following piece of code used by Steve to illustrate how using short routines can improve readability:

if ( node <> NULL ) then
  while ( node.next <> NULL ) do
    node = node.next
    leafName = node.name
  end while
else
  leafName = ""
end if

He points out that this code should be encapsulated in a routine like GetLeafName(node).

An Important Lesson from Objective-C

Fri, 21 Sep 2012 00:00:00 +0000

I’ve started to develop applications for iOS about 3 months ago and there were a lot of things new for me in that environment (there are a lot yet) and Objective-C wasn’t an exception.

The syntax of this programming language is scary the first time you see it but with time you get used to it and you can get a lot of good practices too.

One of the most important things I’ve learnt is that the more self-explanatory a method is, the better. It doesn’t matter how long it is. Actually this is something you can apply to other languages. Let me show you a quick example:

function cleanAllInputValuesAfterValidation(values){}
function sortDirectoriesAlphabetically(directories){}

In fact, in Objective-C you can pass parameters in the middle of the method’s name, which teaches you a couple of things about naming. You can see DHH’s thoughts (the creator of the framework Ruby on Rails) about this here.

Subversion: Remove All the Deleted Files from a Repository

Tue, 04 Sep 2012 00:00:00 +0000

In order to remove all the files from the repository after they have been deleted from disk you have a couple of options.

Using Sed:

svn st | grep '^!' | sed 's/! *//' | xargs -I% svn rm %

Or with AWK:

svn st | grep '^!' | awk '{print $2}' | xargs -I% svn rm %

If you don’t trust these commands (you shouldn’t but nowadays we don’t have enough time right?) you can see the list of files that will be removed from the repository without the xargs part:

svn st | grep '^!' | sed 's/! *//'

Or:

svn st | grep '^!' | awk '{print $2}'

I think AWK is more elegant in this case since it seems more obvious to me to print the second column than removing the “!” part, but that’s just my opinion.

Return at the Beginning of Functions

Fri, 24 Aug 2012 00:00:00 +0000

I had a little doubt about when to do the return if you have a big if, something like the following function:

function animateElements() {
  ...
  if (pool.allAnimationsCompleted) {
    doAnimation1();
    doAnimation2();
    doOtherOperations();
  }
}

In that case all the function is inside of an if, so the following implementation would do the same:

function animateElements() {
  ...
  if (!pool.allAnimationsCompleted) return;

  doAnimation1();
  doAnimation2();
  doOtherOperations();
}

I was totally sure that this was better, because the function is cleaner but recently, after doing some memory management on my own and forgetting some releases I’m not that sure. Let me expose the pros and cons and and a more complex example:

Pros

Less indentation
Cleaner code

Cons

You are breaking the normal flow of a function, which is returning something after doing all the operations, this is critically important if you have to release some resources and the function returns before the execution of those lines. This could happen in a slightly different case:

function createElements() {
  var elem1 = createElement();
  var square = createSquare();

  if (square == null) return;

  elem1.doSomething();
  removeElement(elem1);
}

In my opinion, it’s not as readable as the normal flow, with an if, even if this if is huge.

Conclusion

I’m not sure if in the first case is better to put that return, but after the leaks I had (I was working with Objective-C) if the function is more complex and the return is in the middle, in my opinion it’s better to have something like this:

function createElements() {
  var elem1 = createElement();
  var square = createSquare();

  if (square != null) {
    elem1.doSomething();
  }

  removeElement(elem1);
}

For the rest of cases, an early exit at the top if some precondition is not met seems good enough to me.

Origin of HTML Radio Buttons

Tue, 03 Jul 2012 00:00:00 +0000

The radio buttons in HTML come in handy when the user should select only one option in a form.

The HTML looks like this:

<input type="radio" id="mac" name="computer" value="mac">
<label for="mac">Mac</label>

<input type="radio" name="computer" value="pc" id="pc">
<label for="pc">PC</label>

<input type="radio" name="computer" value="hackintosh" id="hackintosh">
<label for="hackintosh">Hackintosh</label>

This element was called radio buttons because of the behaviour of the old car radios, where you could keep pushed only one button at the same time.

IPad Acceleration with Javascript

Sat, 09 Jun 2012 00:00:00 +0000

It’s well known that Apple supports HTML5 from the very beginning, that comes with a lot of advantages for Javascript developers. One of them is knowing the exact position of the iPad using a couple of events.

First of all I have to say I’ve only tested this with an Ipad 2 with iOS 5, but it should work too with the new iPad (a.k.a. iPad 3).

In order to know what’s the position of an iPad we can use the Device Motion Event, specified by the W3C here. For my purpose I only use 3 variables:

window.addEventListener('devicemotion', function (e) {
  x = e.accelerationIncludingGravity.x;
  y = e.accelerationIncludingGravity.y;
  z = e.accelerationIncludingGravity.z;
}, false);

Once we have these variables it’s all about testing and playing with ranges of values. What I did was creating some messages after I detect a certain position, for instance, when the iPad is in landscape or portrait position using a function executed every 10ms.

mainLoop = setInterval("moveMe()", 10);

function moveMe() {
  // here you check what's the value of a, y, and z
  // and it's checked every 10 ms
}

I know, it would be great to have a little plugin to detect the different positions and trigger events accordingly, but I don’t own an iPad yet so I can only test with borrowed iPads :(

Starting to Learn Python (for Programmers)

Tue, 22 May 2012 00:00:00 +0000

Some months ago I started to learn Python, I found a lot of resources and not all of them were really useful, they were either for non-programmers or too long for an introduction. After some research I came up with a list of resources.

Apart from the links and all the hours reading and studying I find really important to create little projects that I can finish and publish.

I think these projects have two advantages, on one side you can see that Python (or any language you are learning) can be actually used for something that you were trying to resolve. On the other, you are able to build it all by yourself (and that will encourage you to keep learning).