Forem: Josep Jaume Rey

An Ode to Code Reviews

Josep Jaume Rey — Tue, 21 Jan 2020 00:00:00 +0000

At Codegram, we truly believe that Code Reviews are a crucial activity in any software development endeavor. That's a mantra we've been repeating over and over inside our company, but honestly, we think we can get way better at it.

This article is an ode to the beauties of Code Reviews and how they can make your team share better & be more accountable for its decisions while making it all more enjoyable for everyone. We'll explore why peer reviews matter and we'll introduce an idea — the Review Buddy — to help you improve the way you review code as a team. But first...

❓What even is a Code Review?

Code Reviews are a quality assurance process in which a developer exposes their code to an individual or a team in order to get feedback and change it until a consensus is achieved. Depending on your tool of choice, you're going to use GitHub's Pull Requests, GitLab's Merge Requests and so on.

🙃 But why code review at all?

We developers love code so much that we'd probably rather spend all day throwing lines at the editor , leaving aside other mundane activities like meetings, answering e-mails or... reviewing other people's code.

That's okay and sure everybody can understand that feeling. We just love code so much! But writing code is not a science but rather an engineering task (some might say there's even some art in it), and successful engineers take the human factor into account every step of the way.

"Taking the human factor into account". A-ha.

See, what's made of a bunch of humans? Teams! So let's take a step back and think about what we're collaborating over: code. If we look at programming languages themselves, they're not meant to just solve the problem at hand, they're also meant to be expressive, clean and reusable. Arguably, sometimes at the expense of efficiency solving the problem itself.

Why is that? Because we care about how other humans (or the future human you!) deal with code so they can understand it, build on top of it, extend it and re-shape it as pleased.

If you think about it, code reviews are the ultimate form of expressiveness. They just happen to encompass another dimension: time. When you create a Pull Request on GitHub, you do it to solve a specific need at that moment in time, with a specific context in mind that might change in the future.

Maybe a colleague — or yourself — need to revisit a decision you made a while ago and hey, revisiting that nice Pull Request might just be what you need.

You might be thinking: Okay, so code reviews are mainly a bookkeeping tool. Yes and no! They are way more powerful than that. Keep reading to know why (mini-clickbait) 👇🏼!

🧠 Code Reviews help with knowledge transfer.

If you're reading this, you're probably the curious type. Being curious in the tech industry usually means constantly looking for new & effective solutions to solve your everyday problems, or even trying to jump to that new cool framework and going for a quick ride on the hype train.

What's better for that than being able to see what other humans are doing? Code Reviews enable precisely this - the ability to peek into someone else's code to learn new stuff.

🤝 Code Reviews create a sense of shared responsibility.

Continuously having to make decisions on your own on a piece of code without any help, let alone a whole project is mentally draining & stressful. By having others review your code, you'll be able to get some relief while knowing there'll be someone else there for you in times of need. ~~And that can be the start of a friendship that lasts forever.~~

👀 Code Reviews will improve code quality even when nobody is watching.

You might be familiar with the "rubber duck debugging" technique, a concept introduced in The Pragmatic Programmer book. Dave Thomas, the author, makes a case on how the mere act of explaining code to a peer can help you debug a problem without any actual interaction needed — so we might as well be talking to a rubber duck 🦆.

I like to think the same principle applies to Code Reviews as well. By writing code as if someone would review it (even it that doesn't happen), you're going to write better code.

*Rule of thumb: Assume you always have a bunch of ducks around when writing and delivering code.*

But the humans...?

Ok, back to the main point! When you do get your code reviewed by other humans:

You gain a better understanding of your own decisions by being questioned over them.
You will get useful contributions that can help to fix bugs, to find new edge cases, and maybe even lead to rethinking a flawed architecture.
You will learn from people that might have more experience or insights about a particular area.

🤩 OMG Code reviews are so cool!

Code Review all the things!

...so why don't we do it more often? Well, I think that's because coming up with an effective way to present & review code is hard by nature. And because of that, some people see it as a burden and put it in the same box as reading e-mails or attending meetings.

Let me introduce you to some advice on how Pull Requests need to be dealt with at the grass-roots level, and then we can talk about team dynamics, which is a whole different thing.

🦄 Here's how to step up your code reviewing game

There are three sides to every story: yours, mine & the truth.— anonymous, but also the title of a rock album I really like

As an author, you should:

Be verbose and provide enough context: A Pull Request needs to have a clear structure & description. More than what and how — which can often be guessed by the code itself — one must focus on the Why. Why did you choose a particular path? Were you under a tight deadline and did you have to compromise? Whom does it affect? Does this affect any business logic?
Write tests: Tests are a great way to express the boundaries of a problem and provide specific examples of how the code behaves in real-life scenarios. Reviewers will appreciate having them gain a better understanding (and your customers probably will too, but that's another story)!
Checks, checks everywhere: GitHub, GitLab, et al allow for automated checks such as linters, code coverage analysis, and others to be embedded just within your Pull Request. By doing that, we leave some low-value topics such as styling out of the conversation and let our dear reviewers focus on what's important.
Get your Pull Request deployed somewhere : Sometimes seeing something is better than just reading about its internals. Using tools like Heroku's Review Apps or Netlify's Deploy Previews can be really helpful, providing a separate deployment per Pull Request.
Don't let your Pull Requests block your progress : Quality code reviews take some time and you don't want to rush people into accepting them just because they're blocking you. If you're being smart about it, you'll have come up with an architecture that will allow you to have multiple Pull Requests going on without one depending on another. It takes some practice and it's not always possible, but it's definitely worth the effort!
Don't take criticism personally: When getting your code reviewed, you might sometimes feel personally attacked. That feeling might come from a vulnerable position — am I not smart enough? — or even from a defensive position — they're over their head! Just keep in mind you are not your code. Take a breathe and remember: they're challenging your code, not you.
Be cooperative: Even if you think a reviewer's suggestion isn't right, be cooperative and walk them along with why you think that's the case. Dismissing another person's opinions just because isn't nice — think about how you'd want to be treated if the situation was reversed. Plus, if you think the issue lies in the reviewer not understanding the problem at hand, chances are you didn't provide enough context, to begin with.

As a reviewer, you should:

Be empathetic: Keep in mind a Pull Request done properly took a lot of effort. You'll get a way better conversation if you keep an upbeat, engaging tone in your comments.
Write thoughtful, unambiguous comments: Tone is difficult to grasp on written communication. Be sure you don't leave space for ambiguity and that your writing is clear & concise while providing enough context.
Suggest specific changes : If you think something can be improved, don't just say so, suggest a specific change. But again, don't just suggest a change, it can stike the other side as passive-aggressive. Take some time to explain why you think something can be changed.
Don't be judgmental: There are lots of reasons why code doesn't look the way you think it should look. Don't make judgments and try to understand why they came up with that particular solution. After all, you're both aiming at the same goal.
If you need it, download the code and run it: Superficial reviews are not useful at all. It's a temptation you need to fight. If you need to, download the code and run it. It's fun!
Beware of the impostor syndrome: Have confidence in your feelings on the code and don't be afraid to start a discussion, even when reviewing more experienced developers' code. Also, comments on Code Reviews don't always need to be about suggestions - asking questions to gain better understanding of what's happening is perfectly fine.
Be responsive: When asking for changes, don't just leave and come back days after just to find your suggestions addressed in a couple of minutes. That's not nice. Just keep on top of what you review so everybody can get done with it!

🖖 Nice tips! Give me my CodeReviewMaster© shirt already.

Well, wait a minute. These tips & tricks are really cool, but for these to work, Code Reviews need to actually happen. As it turns out, that isn't always that easy. It certainly isn't for us, being a consultancy that works in lots of different projects at the same time. Why is that?

On one hand, when working within a really small team, getting quality code reviews can be hard: Imagine you're working on a project and you're the only front-end developer. Who can review your outstanding Vue.js code if there's no one else in the team that knows about it? You could always ask someone else outside of the team, but then, on the other hand, collaboration cross-project is just tedious. Creating a #code-reviews channel on Slack where everybody can go get their PRs reviewed looked like a nice idea at first, but doesn't really cut it. You can't possibly get valuable reviews out of them -- reviewers are missing a lot of context due to them not being actively involved on the project. Soon enough, the channel ends up being cluttered of unanswered cries for help and, eventually, people stop asking for reviews at all.

One could reach the conclusion that Code Reviews can only happen in mid-sized teams and up , and that collaborating outside of the team's boundaries is just a pipe dream. A sad reality to live in.

😓 So we're doomed. Back to writing code alone in the dark.

Coding alone with a blanket at night

Please don't close this tab yet! We've come up with ways to get your Code Reviews to be way more effective! Or at least, we think so 😏.

We're about to change how we collaborate over code at Codegram and we expect this will lead to improved team dynamics (see! I said we would talk about it). Code Reviews are about to be second-class citizens no longer. Here's our plan:

Every developer working alone on a project or in an area will get a review buddy : A review buddy might not need to be involved in the actual coding, but will be there to preventing PRs from becoming stale with their helpful reviews. A review buddy knows about the history of a project and thus understands all the decisions behind every step taken, leading to in-depth, spot-on appreciations. A review buddy has no reason to ignore your PRs. A review buddy is your best friend.
Developers can still ask someone else for help: In the event that a developer and their review buddy (I love this name) are stuck, they can always ask for help to someone else — since they won't receive a constant stream of impersonal review requests anymore, they'll appreciate being chosen for the task and be more willing to help. Note than one must keep the list of reviewers short for this to work.
We'll leverage better tools: We'll ditch that #code-reviews channel on Slack and promote the use of other tools like Pull Reminders — a free Slack integration that will keep in touch with every developer and make sure they follow up on their duties. In addition, using GitHub's CODEOWNERS file in our projects will also help to streamline the process of asking for Code Reviews in the first place.

It's just three simple steps but we expect them to have a high impact leading to healthier reviews, happier developers, and, in the end, better software. Sometimes things are not that complicated!

🚀 Collaboration doesn't stop on Code Reviews

While we've seen Code Reviews are incredibly useful, they're not the one and only way to collaborate over code. Sometimes you just need to do some pair programming - and that's an incredibly nice experience when you really need it! At Codegram, we particularly like Visual Studio Code's Live Share feature and we use it quite a lot. Damn, it looks like Microsoft is killing it these days.

Finally, you should always keep in mind that everything said in this article can't make up for missing documentation or bad architecture. More than that — clean, documented code leads to easier-to-deal-with Code Reviews, and Code Reviews can help you keep your code clean & documented. Use that power for good!

Did you seriously think there wouldn't be any Baby Yodas in this article?

👋 That'll be all!

I hope you've enjoyed my humble views on the topic — with any luck it'll have inspired you to adopt some or all of these techniques and that'll help you and your team to be more collaborative. Or maybe you just think this is bananas!

In any case, I'd love to hear your feedback — you can send us an e-mail to hello@codegram.com, ping us on Twitter at @codegram or just yell at the programming gods!

Adopting the JAMStack: Building CMS-backed static websites with Vue or React

Josep Jaume Rey — Mon, 12 Aug 2019 13:59:01 +0000

Originally published at Codegram's blog

Note: This post's title could also be called forget about Wordpress and Drupal but after a bit of thinking I thought it wouldn't be a fair comparison since they're also really good tools. But in a way, it would be. Well, keep reading to find out why!

Hello! So if you're here, you've probably heard about the JAMStack already, or you're curious about it. Cool cool cool. I was too - hopefully, this post will probably save you some time if you're looking to get started into it.

What's the JAMStack?

The word JAMStack started being used just a few years ago. It stands for JavaScript, APIs, Markup as stated on their official website. It's not about specific languages or technologies, but rather an abstract definition of a runtime & deployment chain.

The term was coined by Netlify - but the tools & concepts behind it have been there for a long time. It just turns out that when presented together, they pack a lot of punch:

Statically generated sites
Using the latest JavaScript frameworks & libraries
Leveraging APIs (REST, GraphQL, or anything else)
Deploying to a CDN
Atomic deployments
Automated deployments via WebHooks
Plays really nice with Serverless

The benefits it provides are generous:

Unbeatable Time To First Byte : Since we'll be using CDNs to serve our whole request cycle, the time spent by the browser trying to get our first bytes of information is only limited by the CDN.
Zero-time deployments: There's no boot time associated with deployments, which means new deploys or rollbacks are instantaneous.
Security: The surface area for attack is greatly reduced, as most of our requests are now served by battle-tested CDNs that don't have direct contact with our APIs.
Simpler model : JAMStack's is a nice breeze of air in a world dominated by Docker, Kubernetes, Buildpacks & such.
Straightforward scalability: If your website isn't using APIs at run-time (the website is entirely statically built), you'll have the certainty your website can't go down because of a huge spike in traffic.
Decoupling presentation from data : By separating the data source from the actual application, we get a greater choice of technologies. While this is true for many SPA, going the JAMStack way forces you, which is RealGood™️.

No doubt, no doubt. Should I use it?

As most technologies, the JAMStack is not for everyone. But it certainly is the right tool for you if you're building:

A website that's mostly public, backed by a server-side CMS (say WordPress, Drupal, Joomla...).
A Single Page Application
Any kind of typical monolithic application that has a lot more reads than writes.

It might have other use cases, but at the moment these are the scenarios where I've felt myself most comfortable using it. And I'm really loving it.

A good use case would be Smashing Magazine: they're running on the JAMStack!

How does the developer experience look like?

I've previously said one of the huge selling points of the JAMStack is the developer experience. Here's how a regular development day will look you if you embrace the JAMStack:

You write your website in your favorite technology: Vue, React , or even plain HTML/JS/CSS - in practice, you'll use some of the build tools I'll talk about later on. You tie its rendering to some external API's data, namely a Headless CMS (I'll talk about it after a bit too!)
You push your website to your favorite Git provider: GitHub, BitBucket, etc.
During your deployment, your website fetches all the needed data from your APIs and gets statically built , generating a bunch of HTML, JS & CSS in the way.
Your site gets published to a CDN
Users visit your website and get served static data all the way along, so you don't have to worry about scaling your APIs - the data is embedded in your markup.
When your content changes on your source of data, a webhook gets fired, rebuilding and redeploying the whole website.

You can probably already see how all this plays extremely nice with automation tools like GitHub actions or even Zapier. Huge win!

Sold. How can I start using it today?

I'm sure there's a lot more tools and services I'm missing, but here's a compilation of the ones I've had experience using and I can actually recommend!

Web application frameworks

The first step in building our JAMStack-enabled site will be selecting our framework-of-choice.

Gatsby

Gatsby is one of the most ambitious projects to support the JAMStack. Built with React, it allows embedding nearly any kind of data source into their internal GraphQL database for you to query. All the queried data will get statically built into the templates, making it blazing fast!

In my experience, working with their GraphQL api can be a bit cumbersome and somehow limited, especially when it comes to relational data or other complex queries, but my experience is limited and a bit outdated - this might have changed on the last few months. That said, it's a great project with outstanding innovations like automatic responsive images, PWA support out of the box, and more.

Gridsome

Gridsome is a newcomer and the Vue equivalent (equivualent?) to Gatsby. Still in its early stages, it looks really promising.

While it lacks the bigger ecosystem Gatsby has, it has picked up on their latest features and improved on them, and I personally expect it to move quite fast. Their documentation is getting better every day.

We've build the website for Full Stack Fest 2019 with it, and it's been great. Just check out how fast it is!

Nuxt.js

Nuxt is the dominant framework when it comes to building web applications with Vue.js. Inspired by Next.js (its counterpart in the React world), it provides a statically generated mode that will embed the data used in your pages in your HTML templates.

There's only one gotcha: Calls to the original data API will still happen on page transitions. It looks like they're working on it and they're conscious of their limitations, based on our recent tweet exchange.

Nuxt has great support for i18n and a big ecosystem. Worth checking it out!

Headless CMSs

The big eye-opener for me has been finding out that I can definitely delegate the CMS to an external provider. While some use cases are calling out for a tailored backend, most use cases are simple enough that can configured via a UI. Nobody likes having to reinvent the wheel over and over!

There's many of them, but I'll only describe the ones I have actually tried in production.

Contentful

Contentful is undoubtedly the biggest player out there and has recently received a 33.5M$ funding round, so it isn't going anywhere.

Its backend is quite simple and flexible to most use cases, including support for I18n fields, content relationships, a rich HTML content editor, and more. However, it's unexpectedly expensive. They have a free plan that might work for most use cases, though.

Their data is exposed via a REST API, but they have a GraphQL one on bigger plans though.

Prismic

Prismic has an outstanding UI and user experience. It has support for I18n documents, associations, responsive images, and many kinds of fields. They also have tools for working for the major JS frameworks, a great querying API, and more. They're working on a GraphQL API as well which will be hopefully available to the public soon!

My experience working with them is pretty extensive and so far their response times have always been steady and reliable (which is one of the core things you're looking for when delegating your content to an external platform). Worth checking them out!

Deployment platforms

I'm sure there's plenty of options out there to deploying static content, but I'll list just what I can recommend:

Netlify

Netlify it's just perfect for the JAMStack — notably, their CEO came up with the term — so expect it to support everything they need and more, including:

Cached, automatic builds
Deployment previews, sync'd with GitHub's PRs
A/B testing
Support for Serverless functions

My experience using Netlify has been amazing from moment one. Did I mention they're free for individual plans?

No, I'm not working for them or nor do I have any kind of agreement. I just love it.

Your CI of choice + S3 + [CloudFront|CloudFlare|.*]

As in the end you're only deploying static sites, using your own CI to lint & build and then deploy to AWS S3 or similar is perfectly fine. You will just have to write part of the pipeline; rollbacks, deploy previews, etc.

My recommendation : If you want to leverage your own CDN, just back it with Netlify 👌

Giving you some time to rest and let it sink

Things that I've learned working with the JAMStack

Rebuilding after every change is totally fine

If your website isn't incredibly dynamic by nature, rebuilding after every change is perfectly fine: you're consuming CPU time in advance in exchange of saving the time spent on the runtime by your server mangling with html strings. Isn't that a great tradeoff? After all, aren't we throwing thousands of hours into our CIs already anyway? As an example, we have a webhook that rebuilds our Full Stack Fest 2019 website every time a podcast episode gets published. Working with client projects, we set it up so the whole site gets rebuilt every time a news article gets published (which happens several times a day).

Highly dynamic content can also be served

If some of your content is highly dynamic, there's nothing wrong with it — you can always resort to consuming an external API on runtime. This is the case for comments, for example. Gridsome, Nuxt & co allows you to defer the rendering of part of your component tree to the client. This is actually great for UX - the user gets server-side content as soon as possible, while the rest of the page gets load asynchronously. This also works for admin panels, private user areas & more!

It's nice having your HTML back

Having your application boil down to a bunch of static files kind of reminds you how the web was in the GoodOldDays™️. This enables new possibilities like Progressive Web Applications , publishing to the P2P web (see Beaker and DAT) & more!

It helps with SEO

While sometimes a limitation, not being able to dynamically change your served content depending on the client's headers (see I18n) forces you down a path that actually helps with SEO. That, and the fact that the content gets served blazingly fast, adds up to a happy google bot.

I want moar

Pheeew, that was quite a brain dump!

If you're eager to learning more about the JAMStack, here's some great resources to learn from:

The Full Stack Fest 2019 conference (which we happen to organize at Codegram) features Brian Douglas , one of the original proponents of the JAMStack and he's also the host of the JAMStack radio podcast. Boom, shameless plug!
JAMStack Newsletter: A newsletter about the JAMStack curated by Netlify.
Awesome JAMStack: A compilation of resources following the awesome-* repo series.
Other resources : The JAMStack website features other resources like talks and articles about it.

Thanks for reading this and I hope it will help you get started into the JAMStack world!

Looking for someone to help you build your next project on the **JAMStack? Throw us a line at hello@codegram.com and we'll be glad to help you!