Forem: Ricardo Lopes

No Surprises

Ricardo Lopes — Mon, 19 Feb 2024 00:06:37 +0000

One of my principles for software development is “no surprises”. Things should be exactly where we expect them to be, and look exactly like what we expect them to look like. Code should do exactly what we expect it to do.

When things are surprising, we have to spend more mental effort trying to understand them. If we can't trust a codebase to have no surprises, we're constantly on high alert.

When code has no surprises, there's a whole cognitive load that is no longer needed. We can get into a focused flow state, knowing that we can trust the code we see and don't need to second-guess everything.

Here are some examples of how to apply this principle, in no particular order.

Consistent style

Enforce a linter and autoformatter.

I don't care which rules you choose. The important part is to have consistent rules applied everywhere. This will make all code look consistent and predictable, so that no one has to spend time or effort with style decisions.

Don't make developers discuss style in pull requests. It has to be a solved problem at that point.

Clear project structure

If you've got a models directory, don't put models files anywhere else.

If one endpoint calls a service that calls a model, don't have another endpoint calling a manager that calls a repository that calls the database directly.

When a developer is working on a new feature, they should never need to spend time deciding what the structure should be like: they should just need to follow the project convention.

Also: keep the project structure easy to understand and to apply for new code.

No hidden consequences

If you're calling a GET endpoint, you're not expecting it to mutate data.

If you're calling a model method, you're not expecting calls to external providers.

When these assumptions fail, it not only forces the developer to spend more time hunting for those hidden consequences, but it's also a common source of bugs.

No needlessly defensive code

If email is a required field for users, you don't need to protect against a missing email in the rest of the codebase.

If an endpoint returns a list of resources, you don't need to protect against a 404 when no resources exist: the response is a 200 with an empty list.

If a module requires a user to be an admin to reach it, you don't need to repeat that check inside the module.

This sort of needlessly defensive code is protecting against threats that don't exist, and is casting doubts onto developer's minds (wait, email could be undefined at this point??).

Industry conventions

Write idiomatic code, use the framework's conventions, follow best practices.

You don't need to blindly cargo cult what everyone else is doing, or apply conventions that don't make sense for your specific situation. But often it's useful to look for common patterns and solutions that the industry has reached consensus on, which could benefit you as well.

This allows you not only to benefit from the wisdom of the crowd, but also to keep surprises low when switching between projects and teams.

The right abstraction

The platform you're developing on provides a set of APIs and tools you and everyone else can use.

Unneeded custom abstractions and complexity on top of that common interface will look surprising and require more mental effort to understand and to look for unexpected behaviours. Not to mention more surface area for maintenance work and bugs.

And more

I'm sure there are a lot more examples of this principle. I may update this list in the future, if something else meaningful comes up. But I hope its message is clear already.

Make your code as boring and as unsurprising as possible. The mental load from dealing with surprises and uncertainty may not seem much to you, at first, but it compounds, eventually turning a project into a fragile unmaintainable mess that developers are too afraid to touch.

I hope none of this sounds too surprising :)

Being Uplifting

Ricardo Lopes — Sat, 10 Feb 2024 02:00:39 +0000

When someone chooses a career, they go for the work they like the most, within their abilities. I know I did when I followed software development. And yet, you don't see many people celebrating Mondays and lamenting the end of the week. Not even close.

Somewhere along the way, we all experience the office politics, the bad management, the boring tasks, the lack of agency, and so on.

We love the craft, but not necessarily the job.

In all the teams I've worked with, I've never seen an ideal scenario where nothing is wrong. And I don't think I will, ever. And neither will you. The real world is always messy.

It's up to us to decide how we want to react to everything that is wrong around us.

"We have absolutely no control over what happens to us in life but what we have paramount control over is how we respond to those events."

Viktor Frankl

Being a complainer

Early in my career, I wouldn't shy away from the opportunity to complain about everything that was wrong with the codebase and with the company. Something was wrong, so someone had to complain about it!

Asked to waste time fixing data inconsistencies rather than addressing their root cause? What a prioritisation failure from leadership! Long build times slowing down development? What a terrible mess we've inherited from those who coded that in the first place!

It truly felt like an important service to raise awareness of issues that were holding the company's mission back.

Over time, I got more experience, and more respect from peers. I was still an individual contributor, but was naturally doing more and more mentoring work.

One day, I was mentoring two recently-joined junior developers who were still learning how things worked. I was trying to be helpful and authentic, so I made sure to highlight plenty of issues with the codebase and with the organisation. It's useful to know the pitfalls to look out for, after all. All in good spirits.

Later, I had a conversation with my team lead, who learned about that session. That's where I had one of the biggest realisations of my career.

Being intentional

See, my intentions surely were pure, but I wasn't being the helpful mentor I thought I was: I was just being a complainer. I was just ranting about all the things I disliked.

As newly joined junior developers, they looked up to more established senior developers to form their opinion about what they've just signed up for. And if established senior developers paint such a gloomy picture, that's what they assume as true.

This sounds obvious in hindsight, but sometimes we need the timely reminder: if you've got a balanced view about something, but you overly focus on the bad parts, then you're not sharing an accurate representation of your views. Others can't read your mind, only interpret your actions, so they'll believe your views are the non-representative picture you've shared.

So, don't be a complainer. Instead, be intentional, a fair reporter of your full range of opinions. This is especially important if there are people looking up to you and valuing and trusting what you're saying!

This realisation was critical to set the stage for the next one.

Being uplifting

Not long after that episode, something else clicked for me. My mood can easily be influenced by the environment around me. If it's full of complainers, I'll be a complainer, too. If morale is low, mine will be as well.

After having contributed for so long to an environment of complaining, I realised that actually, culture isn't set in stone. It's malleable. The culture is set every day by the people who show up. And you're one of them.

No matter how you rank within your company, you are an influencer of its environment. We all are, whether we realise it or not. You can choose to blend in with how others set it, or you can opt for planting a different seed.

"Be the change you wish to see in the world."

Apparently miquoted to Gandhi

Influence the environment you want to be a part of. If you're a complainer, you're enabling an environment of complainers. If you want to be a part of an uplifting environment, it starts with you.

Be an uplifter.

When others complain, you can publicly celebrate your teammates’ successes. When others plot against each other, you can ignore the noise and focus on beating the only one who matters: your past self.

If the tasks are dull, use your spare time to explore and learn new things, rather than using it to rant about how boring things are. If your company offers a learning budget, make good use of it!

Be intentional with the way you interact with others. Make them feel valued and filled with energy, even on days when you don't feel that energetic yourself. People remember how you made them feel. And they act accordingly.

This isn't about dropping your authenticity and pretending to be someone you're not, or sharing opinions that aren't what you truly think. It's about realising that your actions have consequences, and you can be intentional in surfacing your best self.

This is also not about toxic positivity. It's still important to flag issues and to try to fix them. We shouldn't self-censor any criticism, we should just be more strategical about when it's actually useful to share it, and being constructive about it.

This is about lifting others up: showing excitement about things, not ranting all the time for the sake of it, openly celebrating success, being kind to team members, and so on.

And, when in doubt, you can slightly exaggerate these positive behaviours. Communication is hard, especially if you're remote, for instance, or when writing. So, slight exaggerations go a long way in removing ambiguity or misunderstandings.

Is this mindset change a silver bullet against everything that is wrong with a job? Of course not! And if you're in an awful environment, your best option may be to look for something better.

But for your everyday job, I've seen this mindset shift improve not just my day to day, but also the morale of the rest of the team. And I'm just a recovering complainer, still with much to improve here myself.

Start contributing to the culture you want to be a part of. Don't be a complainer. Instead, be intentionally uplifting: share your full range of opinions, but focus on abundant positivity towards your teammates and saving rants for when they're actually useful.

It starts with you.

Resist Exploding Complexity

Ricardo Lopes — Sun, 04 Feb 2024 00:17:07 +0000

Building web applications seems to be getting more and more complex. Abstractions upon abstractions, and fixes for problems caused by fixes for other problems. But does it have to be this way?

There's a place for complex frameworks and architectures, sure. But for many projects, they may be an overkill.

Let's think through first principles and explore what the web platforms offer by default to see how far we can go before starting to explode complexity. This is a thought exercise to challenge assumptions, not a prescription to blindly follow.

If we browse the Node.js documentation, we can get a simple working web server:

const http = require('node:http');

const hostname = '127.0.0.1';
const port = 3000;

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World\n');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

We can test to see if it works:

$ node server.js
Server running at http://127.0.0.1:3000/

$ curl http://127.0.0.1:3000
Hello World

We can adapt the server to use routes for specific endpoints. For instance, it can reply to requests to /, and return 404 otherwise:

// GET /
const getIndex = (req, res) => {
  res.statusCode = 200;
  res.setHeader("Content-Type", "text/plain");
  res.end("Hello World\n");
};

const throwNotFound = (req, res) => {
  res.statusCode = 404;
  res.setHeader("Content-Type", "text/plain");
  res.end("Not Found\n");
};

const server = http.createServer((req, res) => {
  if (req.method === "GET" && req.url === "/") {
    getIndex(req, res);
  } else {
    throwNotFound(req, res);
  }
});

$ curl -i http://127.0.0.1:3000
HTTP/1.1 200 OK
Content-Type: text/plain
...

Hello World

$ curl -i http://127.0.0.1:3000/hello
HTTP/1.1 404 Not Found
Content-Type: text/plain
...

Not Found

Great! We can also return HTML, to serve web pages to the browser:

const getIndex = (req, res) => {
  res.statusCode = 200;
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.end(`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>Hello World</h1>
  </body>
</html>`);
};

$ curl http://127.0.0.1:3000
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>Hello World</h1>
  </body>
</html>

We can also send dynamic data:

// Dynamic list of to-do items (non-persisted)
const todos = ['accept user input'];

// GET /
const getIndex = (req, res) => {
  res.statusCode = 200;
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.end(`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>To-Do:</h1>
    <ul>
${todos.map((todo) => `      <li>${todo}</li>`).join("\n")}
    </ul>
  </body>
</html>\n`);
};

And we can add a new endpoint to create new entries for that dynamic data, once again just following the official documentation:

const querystring = require("node:querystring");

// POST /todos
const postTodo = (req, res) => {
  let body = [];
  req
    .on("data", (chunk) => {
      body.push(chunk);
    })
    .on("end", () => {
      body = Buffer.concat(body).toString();
      const parsedBody = querystring.parse(body);
      if (parsedBody.todo) {
        todos.push(parsedBody.todo);
      }
      res.writeHead(301, { Location: "/" }).end();
    });
};

const server = http.createServer((req, res) => {
  if (req.method === "GET" && req.url === "/") {
    getIndex(req, res);
  } else if (req.method === "POST" && req.url === "/todos") {
    postTodo(req, res);
  } else {
    throwNotFound(req, res);
  }
});

$ curl -L http://127.0.0.1:3000/todos -d "todo=test new endpoint"
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>To-Do:</h1>
    <ul>
      <li>accept user input</li>
      <li>test new endpoint</li>
    </ul>
  </body>
</html>

After that, we can add a form to allow adding new entries through the browser:

const getIndex = (req, res) => {
  res.statusCode = 200;
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.end(`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>To-Do:</h1>
    <form method="POST" action="/todos">
      <input type="text" name="todo" />
      <button type="submit">Add</button>
    </form>
    <ul>
${todos.map((todo) => `      <li>${todo}</li>`).join("\n")}
    </ul>
  </body>
</html>\n`);
};

This may be all good, but it's still only server-side interaction. We want some JavaScript to make client-side interactions that make this feel more like an SPA, without page refreshes. Let's add some progressive enhancement.

The first step is to update the POST /todos endpoint to accept JSON requests from client-side JavaScript, in addition to the HTML form it already supported:

const postTodo = (req, res) => {
  let body = [];
  req
    .on("data", (chunk) => {
      body.push(chunk);
    })
    .on("end", () => {
      body = Buffer.concat(body).toString();
      const isJson = req.headers["content-type"] === "application/json";
      const parsedBody = isJson ? JSON.parse(body) : querystring.parse(body);
      if (parsedBody.todo) {
        todos.push(parsedBody.todo);
      }
      if (isJson) {
        // Return 201 with HTML list if requested from client-side JS
        res.statusCode = 201;
        res.setHeader("Content-Type", "text/html; charset=utf-8");
        res.end(todos.map((todo) => `      <li>${todo}</li>\n`).join(""));
      } else {
        // Return 301 with redirect to GET / if requested from HTML form
        res.writeHead(301, { location: "/" }).end();
      }
    });
};

Notice that the endpoint is returning HTML instead of a JSON object. Both are fine, but HTML responses at least minimise the work required on the client.

With this new support, we can finally add some client-side JavaScript to intercept the form request and use fetch() instead, so that we can add a new entry and update the list with no page refresh:

const getIndex = (req, res) => {
  res.statusCode = 200;
  res.setHeader("Content-Type", "text/html; charset=utf-8");
  res.end(`<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Simple Web Application</title>
    <meta name="viewport" content="width=device-width,initial-scale=1" />
  </head>
  <body>
    <h1>To-Do:</h1>
    <form id="add-todo" method="POST" action="/todos" onsubmit="return postTodo();">
      <input type="text" name="todo" />
      <button type="submit">Add</button>
    </form>
    <ul id="todos">
${todos.map((todo) => `      <li>${todo}</li>`).join("\n")}
    </ul>
    <script>
      function postTodo() {
        const todo = document.getElementById("add-todo").todo;
        const ul = document.getElementById("todos");

        fetch("/todos", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ todo: todo.value })
        })
        .then(response => response.text())
        .then(html => {
          ul.innerHTML = html;
          todo.value = "";
        });

        return false;
      }
    </script>
  </body>
</html>\n`);
};

It works! It's now sending an application/json request that receives a 201 instead of an application/x-www-form-urlencoded with a 301 back to the main page.

We could go on. Next, we'd add editing, deleting, persistence, styling, and so on. We could also do some much-needed refactoring, such as extracting request body parsing and building HTML responses. Or moving the client-side JavaScript into its own file that is requested by the HTML page, to avoid that ugly JavaScript inside a template string. But this post is getting long, and hopefully I've already made my point by now.

The full web application so far is a single JavaScript file with 97 lines, including blank lines, comments and some duplicated code that could probably be simplified. And that's enough to power a web application (frontend and backend) with server-side and progressively enhanced client-side data handling. No React, NextJS or even a build step required. No package.json file needed to install 184726 dependencies full of security and deprecation warnings. No fear that in 6 months this will no longer run because of breaking changes and incompatibilities.

Am I recommending you to follow this exact approach on your next project? Absolutely not! My point isn't that this is the Right Way and anything else is the Wrong Way. My point is that we can resist the exploding complexity of code and abstractions if we don't need them. There's a place for complex frameworks and architectures, but we don't need to expose ourselves to that complexity elsewhere. Or at least we don't need to start from that point.

Let's celebrate the powerful primitives our platforms already provide us, and climb the exploding complexity ladder only when those primitives are no longer sufficient.

About This Blog

Ricardo Lopes — Fri, 02 Feb 2024 01:07:47 +0000

Hi, I'm Ricardo Lopes, a tech lead and backend engineer. Welcome to my blog! This is where I'm sharing a collection of thoughts, experiments, wise advice from my mentors, notes on things I'm reading, and more. All views are my own and not of any employer.

My first goal with this blog is selfish: I want to write about those topics because writing helps clarify my thinking and crystallise what I've learnt. I've been learning so much since I started this journey over a decade ago, if I don't write things down, I risk forgetting important anecdotes and nuggets of wisdom.

But if that were my only goal, I wouldn't need to post anything in public.

I believe I wouldn't be where I am today in my career if it weren't for the exceptional mentors I had along the way. I've learnt a lot from them, and I'm a much better developer today than what I would have been otherwise.

Now that I've benefited from all those lessons, I believe it's my turn to pay it forward and to share what I've learnt with you.

I'm no guru preaching his gospel to his disciples. I don't claim to have all the answers, and I still view myself more as a student, not as a teacher. So this is more about sharing notes as peers of the things that resonated with me the most.

If you're curious and want to learn more, be sure to subscribe and follow along. I hope to make it well worth your time!

You can also follow or DM me on X (formerly Twitter) or LinkedIn.