@nicoespeon's blog

The Proper Way to Decode Arrays (with Zod)

Tue, 24 Mar 2026 00:00:00 GMT

z.array(SomeSchema) is the go-to way to validate arrays in Zod. But it has a catch: if any item fails parsing, the whole array is rejected. All valid or nothing.

And that’s a scenario that comes up more often than you’d think:

An inconsistent third-party API sends one oddly-shaped item in a list of 50
Your backend introduces a breaking change on one field, and suddenly your entire UI is blank

I recently read The Proper Way to Decode Arrays by Lucas Barake, which tackles exactly this problem. The solution uses Effect Schema, and it works!

But I really like to go where my teammates are. Effect has a steep learning curve, and most teams I work with are already using Zod. So I wondered: can we do the same thing without reaching for another library?

Turns out, yes. In about 10 lines.

The helper

import { z } from 'zod'

const DROPPED = Symbol('dropped')

function arrayFromFallible<T extends z.ZodType>(schema: T) {
  return z
    .array(schema.catch(DROPPED as never))
    .transform(items => items.filter(item => item !== DROPPED) as z.output<T>[])
}

Instead of z.array(Todo), you write arrayFromFallible(Todo). That’s it. .parse() returns a type-safe array with the invalid items silently dropped.

const Todo = z.object({
  id: z.number(),
  title: z.string(),
  completed: z.boolean(),
})

const Todos = arrayFromFallible(Todo)

const result = Todos.parse([
  { id: 1, title: 'Buy milk', completed: false },
  { id: 'oops', title: null, completed: 'maybe' },
  { id: 2, title: 'Write blog post', completed: true },
])

// ✅ [{ id: 1, ... }, { id: 2, ... }]

The bad item is gone. The good ones are preserved. Your UI isn’t blank anymore.

How it works

The key is .catch(). When a Zod schema has .catch(value), it returns value instead of throwing on failure. We exploit that in three steps:

.catch(DROPPED as never) wraps the item schema so failed items return a DROPPED symbol instead of failing
z.array(...) parses the full array, now containing a mix of valid items and DROPPED symbols
.transform(...) filters out the DROPPED symbols, keeping only the valid items

Why a Symbol? Because it’s unique by definition: it can’t collide with any actual data in the array. The as never cast is a small lie to satisfy TypeScript, but .transform() cleans it up immediately.

When you might want more

This is a fire-and-forget approach: drop the bad items, keep the good ones. If you need to collect the errors (e.g., to report which items failed and why), you can add some logs inside, like the Effect snippet does:

import { Array, Schema, Either, identity, Predicate, ParseResult } from 'effect'

const ArrayFromFallible = <A, I, R>(schema: Schema.Schema<A, I, R>) =>
  Schema.Array(
    Schema.NullOr(schema).annotations({
      decodingFallback: issue => {
        const formattedIssue = ParseResult.TreeFormatter.formatIssueSync(issue)
        console.warn('[ArrayFromFallible]:\n', formattedIssue)
        return Either.right(null)
      },
    })
  ).pipe(
    Schema.transform(Schema.typeSchema(Schema.Array(schema)), {
      decode: Array.filter(Predicate.isNotNull),
      encode: identity,
      strict: true,
    })
  )

Effect is a great library. But it doesn’t have to be all-or-nothing. Zod can do it fine.

How to export git history in PDF

Sun, 16 Aug 2020 00:00:00 GMT

A friend recently asked me if I knew a trick to generate a somehow clean PDF of a git history, as he needed to share that to a non-technical person.

I used to dig into git history a lot to generate git graphs in the browser (although I don’t maintain this project anymore). So I know some tricks indeed.

The git CLI is a goldmine that’s overlooked. You can retrieve many things from git log, as long as you play around with the options.

Generate a PDF from git history

The first step is to generate a text file from the logs:

git --no-pager log --graph --all --oneline > git-history.txt

Then, you can either convert that .txt into a PDF using an online service (if data is not sensitive): http://www.convertfiles.com/converter.php

Or you can use libreoffice if you don’t want to send your history to some online web converter (thank you @mcassard 👍):

libreoffice --convert-to "pdf" git-history.txt

Let’s decompose the git command

I think this is a good excuse to learn some git options. These can be useful in other contexts:

git --no-pager tells git to not use a pager, so we can get all of the history in one file
log --graph tells the log command to draw a graph representation, because that’s what we’re looking for (we want to see the branches!)
--all will show all commits from all branches (local and remote tracking) and tags, everything 👐
--oneline is a shorthand that abbreviates commits and renders a compact version of the graph (so it’s digestible on a PDF file)

To learn more about git log options, you can have a look at the docs. But it can feel a bit abstract. I recommend you fiddling with the options in a git project to really understand what’s going on!

Prevent VS Code extensions from updating automatically

Mon, 10 Aug 2020 00:00:00 GMT

If you use VS Code, you certainly have a couple of extensions installed.

These extensions have a version number that looks like SemVer: vX.Y.Z. How X, Y, and Z evolve is totally up to the extension author. Good extensions usually provide a Changelog to understand the difference between 2 versions.

At this point, a very legitimate question raises up: when a new version is published, how do you know you need to upgrade? Actually, do you need to upgrade extensions yourself? How do you upgrade a VS Code extension anyway?

If you didn’t notice already, I’ve got good news for you: VS Code automatically checks for extension upgrades. If it finds a more recent version, it will install it and update your extension the next time you open the editor.

It’s good news because that means you don’t have to think about it, you always get the latest version available. It keeps updating in the background.

Now, maybe that’s not the behavior you want. Maybe you’ve got a limited internet bandwidth and you don’t want VS Code to install things under the hood. Or maybe you like to know what’s under the hood and you’d prefer check and install extensions updates yourself.

To prevent VS Code extensions from updating automatically, open the editor settings, and search for “extension auto-update”:

You should see 2 options checked:

Extensions: Auto Check Updates
Extensions: Auto Update

Disable both options. If you still want VS Code to check for updates in the background but install the updates manually, disable the “Auto Update” one.

If you prefer to configure the settings from the JSON file, set the following IDs:

{
  "extensions.autoCheckUpdates": false,
  "extensions.autoUpdate": false
}

Why files open over existing tabs in VS Code and how to change that

Wed, 01 Jan 2020 00:00:00 GMT

Using Visual Studio Code, you probably noticed this behavior:

You click on a file. It opens in a new tab.
You click on another file. It opens the file in the same tab, replacing the previous file.

And that can feel a bit annoying. What if you want to open each file in a new tab when you click them? Why is it behaving like that? 😭

Well, if you look closer, you can notice the tab name is italicised. In fact, this tab is a preview of the file. When you click on a file, you preview its content. Since there can only be one preview tab, the preview will change if you select another file.

Actually, this is a VS Code feature. It’s meant to prevent you from opening 10 different tabs if you are just looking for something, but you don’t intent to keep the files open. That way, you can easily see what’s inside a file, just by clicking on it.

If you want the file to open and stick in it’s own tab, you can double-click on the file name, or on the tab.

OK, but I’d prefer to open files when I click on them. How can I do that?

I hear you. Maybe you usually want to open the files you select and you find that behavior kinda annoying.

It just adds friction because you think the file is open but it’s hard to make the difference with a preview. So you forget, you click on another file and snap, your previous file is gone and you need to go get it again!

I’ve got a good news for you: you can configure this behavior! 😉

To do so, open VS Code settings. Search for “enable preview”. You’ll see a Workbench › Editor: Enable Preview option that’s certainly checked.

Uncheck that to change your editor behavior.

Notice you can also control this behavior for files you open through the Quick Open feature.

When you open a file by its name through the Quick Open feature, it’s probable you want to have it open instead of previewed. If so, uncheck the Workbench › Editor: Enable Preview From Quick Open option too.

Finally, if you prefer to update the settings.json, here are the keys you’re looking for:

{
  "workbench.editor.enablePreview": false,
  "workbench.editor.enablePreviewFromQuickOpen": false
}

How to add colors to plain text copied in VS Code

Tue, 31 Dec 2019 00:00:00 GMT

You might be in a situation where you have a text file open in VS Code, but everything is grey. You have some code written. Maybe it’s CSS, maybe it’s JavaScript, maybe it’s Python. But you don’t have these nice colors that differentiate the variables from the properties, the functions, etc.

Sometimes you end up here because you copy pasted some code from the Internet. Everything looks grey and it seems that VS Code doesn’t “understand” your code. 😭

This is a legit question you have to face when you start using this editor.

Hopefully, there is a simple answer. This is not about editor theme or something, it’s called the syntax highlighting.

If everything is grey, chances are your file is highlighted as a “plain text”. So it’s just a big lump of text, without any syntax.

To add relevant colors, you need to select the correct “language mode”. There are 3 ways to do this.

Manually change the language mode

At the bottom right of the editor, you’ll see “Plain Text” written. Click on this and select the appropriate language from the list.

With the Command Palette

As for every action in VS Code, you can use the Command Palette. Use the shortcut Ctrl+Shift+P and start typing “Change Language Mode”.

It will pop up the list where you can select the appropriate language.

With the shortcut

As you can see in the Command Palette, there’s a default shortcut to change the language mode. On Mac OS, it’s ⌘ M.

You can use this shortcut to open the list directly.

Tadaaaa! Now you have meaningful colors again 🎉

Building a (Crafters) community in Montreal

Sun, 22 Dec 2019 00:00:00 GMT

As we’re approaching the new year, I’m taking some time to reflect on what happened in 2019. In particular, I would like to share my thoughts regarding the Software Crafters community of Montreal.

2018, arriving at Montreal 🛬

That was almost 2 years ago, in February 2018. My wife and I left Paris for a one-way trip to Montreal, Canada. I won’t go into the details of this decision (that would worth a dedicated blog post), but I can tell you today that we’ve found the perfect work-life balance here. We enjoy such a high-quality life that we’ve started to build our family: our daughter, Alice, was born in September 2019. We’re here to stay 👪 🇨🇦

On a personal note, I was really involved in the tech community, back in Paris. Meetups. I did a lot of meetups since 2013. I attended to a lot of them, I talked to some of them and I even got into organizing a few of them: Backbone.js Paris, Paris Web Components and the Best of Web conference I initiated in 2016 with Cyril Balit and other meetup organizers.

When I arrived in Montreal in 2018, I was really looking into joining the tech community.

And certainly more than any other tech meetup, I was looking for some kind of “Software Crafters” community. The one in Paris is huge and one of the most interesting meetups I’ve been to. It’s not yet another group of people interested in some technology or hyped framework who’d watch amateur talks about that technology or framework every month. The “Software Crafters” community is a worldwide group of diverse people who are interested in building high-quality software. Communication and practices matter more than specific tools. We talk about testing, software architecture, how to better understand business problems, how to write maintainable code, how to build great teams, etc.

Software Crafters communities, worldwide

Ok, you got the point.

But when we arrived in Canada in 2018, there was no “Software Crafters” community in Montréal. At all. To be honest, tech meetups, in general, are less popular here than they are in Paris, even today. I’d say that’s cultural. Every day, I’m home before 6pm, sometimes even at 5! In Paris, I was hardly back home before 8pm. That’s 2-3 hours I can spend with my family. Hence, that’s not surprising it’s harder to get people to stay after 7pm to attend a tech meetup compared to Paris!

Still, I knew that a community of Crafters was missing. I mean, there are plenty of developers in Montréal. I bet they also have issues with continuously delivering value to their business without creating bugs in the process. Regardless of the language or company they’re working with, they would certainly love to talk with other people about these issues to find better ways.

All it needed was a spark. I thought I could be that spark. I knew what it looked like, and I organized meetups before. So I created Software Crafters Montréal in September 2018.

2019, a growing community 🌱

I remember the first meetup we had. It was the 4th of September 2019, a Tuesday. 3 people joined. We were 4, sitting around a table. I presented the idea of the meetup.

Indeed, unlike other tech meetups, the “Software Crafters” one has a different format. People don’t come to attend a few talks passively. Instead, the meetup adopts the unconference format: participants drive the content of the meeting.

A typical “Software Crafters” meetup in Montréal looks like that:

People arrive progressively, food is available, that’s networking time where you meet and talk with other participants
All participants regroup, the organizers do a short intro of the meetup for the newcomers and announcements
There is a 30min window for lightning talks. These could be 5min talks with slides, but generally, people spontaneously take 2-3 min to share a book, a blog post or a video they really enjoyed.
Then, all participants can propose topics for discussions. Typical topics could be “Feature branches vs. Trunk based-development” or “Burn-out: how to prevent and recover” or specific needs like “My coworkers don’t want to pair-program, what could I do to make them try?“.
Finally, everyone votes on the proposed topics. The most voted topics got discussed during 1h as we split into groups of ~10 people. Anyone can attend any discussion and move from one group to another if they want to.
That’s it, we regroup for each group to do a summary of what was discussed. Then we say goodbye.

It’s a very social meetup.

Over 2019, the community progressively grew. For the first 4-5 meetups, we were less than 10 participants, with a no-show rate of ~40%. The “no-show rate” is the percentage of people who registered, but finally didn’t show up. For tech meetups, I’d say the average rate in Montréal is 50% since these events are free.

In the 3 last meetups, we were about 25 to attend, with a no-show rate of ~33%.

That makes me really happy. I don’t care much about the numbers as long as the quality is here. I can feel the community is growing. I met a lot of new people. I saw people coming back. I saw people bringing friends. Every meetup, I connect with new persons and I see familiar faces. And we always have insightful topics. At the last meetup, I was in the group talking about burn-out (preventing it and recovering from it) which triggered powerful feedbacks from people who experienced it. The other group was a roundtable of everyone sharing the tools that saved them a lot of time. A lot of helpful tips and links were shared.

List of tools that were shared

Retrospectively, in 2019 we did:

1 regular meetup every month (so 12 in total)
2 special meetups with guests:
- J. B. Rainsberger who improvised an amazing workshop on universal software architecture
- Adam Dymitruk who did a workshop on CQRS and Event Sourcing
2 dojos “Introduction to TDD” animated by Christophe Fernandez
We participated in the Global Day of Coderetreat, hosting an event in Montréal

All of that was possible thanks to the different hosts and sponsors we had. But most of all, 2 companies really supported us in this initiative:

Busbud, my employer, which sponsors and hosts the meetup since the very beginning. They give me full support to do what I need to make all of this happens, playing a big part in making this even possible.
Zenika, a French consulting company that recently arrived in Canada. Their consultants are really into Craft, so they know what they’re talking about. Actually, a lot of Zenika consultants participate in the monthly meetup.

If I ignited the meetup in September 2018, two people rapidly helped me make the flame grow: Damien Beaufils co-organizes the meetups with me since April 2019 and Khaled Souf joined us when he arrived in Canada in November—but he started providing support remotely before that, helping me to get in touch with Adam Dymitruk. Not surprisingly, these two great people were part of the Software Crafters Paris community and are Zenika consultants 😉

2020, to many more 🍻

End of 2018, I was the one guy organizing a meetup of ~7 persons at Busbud every month.

End of 2019, we’re 3 organizers who bring ~25 people every month to different venues in Montréal for regular or special meetups.

I think the community will continue to gently grow in 2020. Maybe we’d be ~50 every month to join and talk.

At least, here’s what we’ve planned for 2020:

Our monthly meetup, as usual, every 1st Wednesday of the month
Another monthly event, oriented on hands-on and practice (think “coding dojo”). We did 2 experimental dojos on TDD in 2019. We’ll have that every month in 2020. Thanks to Badradine Boulahia who’s joining us in the organization, we’ll have the bandwidth to make that happens. It’s called “Craft your skills” and it will occur every 3rd Wednesday of the month.
The very first SoCraTes Canada conference. We’ll bring 20 people in a lodge near Mont-Tremblant in March, for 2 days. Craft discussions, coding dojos, snow and fun to be expected 🍁
Punctual special meetups if there is a special guest in town. Who knows.

That’s it. 2019 is about to end and I’m really proud to realize how much the Craft community of Montréal is developing.

To many more!

If you want to get in touch, you can join us on Slack, channel #montreal: http://slack.softwarecraftsmanship.org/

My tips and tricks to help you build such a community 📝

I was recently asked if I could provide some advice to people who’d like to build such a community. I think that could be useful to you, so let me share that here.

First of all, if you’re willing to build it, thank you. It takes someone to take the initiative. Thanks for being that person ❤️

It takes courage to create something from the void.

Nothing is in place, you have to set up everything. You’ll have to explain something new to people again, and again. Don’t give up. Push it through. It’s fine to have only 3 people attending.

After a few months, you’ll see more and more people attend. Communities are built through time.

Be consistent.

Make sure people can count on you. Have a clear frequency for the meetup (e.g. 1st Wednesday of the month). That helps to set a pace. It will also push you to find a place and a sponsor.

Don’t do this alone.

Check if your employer can host/sponsor the first meetups. That helps. If not, ask around.

After some time, tell your community you’re looking for co-organizers. They will help you carry the load. You want the community to live even when you can’t attend because you’re enjoying holidays with your family!

In doubt, ask.

If you don’t, then it’s already a “no”.

If you ask, you increase the odds of getting a “yes”.

That’s why I pinged JBrains and Adam Dymitruk when I learned they were in town. “Hey, do you think we could set up something with the community and you when you’re here?“. It’s not bold. It’s the only way to make good things happen. Surprisingly, they said “yes” and we all had a great time. So go ahead, ask!

Propose other kinds of food than pizzas-beers.

I mean, these are convenient and quite cheap. But that’s not super healthy food. Sometimes, that’s just a sloppy organizer fallback.

If you look a bit around, you can find alternatives. Sushis, for example. They are not much more expensive than pizzas because people will eat less of them.

If you have enough time before the event, you can even go to a supermarket to bring some fruits, chips, nuts, snacks, bread, cheese, vegetables… Whatever you want. People like that better and are not used to it.

Account for the no-show.

I’d recommend keeping track of it, so you can anticipate the food better.

It’s fine to do mistakes at first. But you can progressively adjust. After some time, you’ll have a good idea of how much sushis to order regarding the number of attendees (for us, it’s the number of registered people x 4.5).

Don’t open registrations until 1 week before the event.

To limit the no-show. Otherwise, people register and forget.

It’s also a good idea to send a short email the day before to ask people to free their spot if they finally can’t attend.

Celebrate!

For the meetup 1-year anniversary, I bought a little cake (thanks to sponsors) and had a little word. It was a chill moment.

The community we’re building is not just another “XYZ Framework” meetup. It’s a social group of people who want to have meaningful conversations with others.

These kinds of moments make everyone feel we’re part of a human community. I believe that’s part of why our no-show rate is lower than other tech meetups out there. And most of all: it feels good.

Workshop: Build your First VS Code Extension

Fri, 20 Dec 2019 00:00:00 GMT

This is a workshop / live-coding talk I gave at Node+JS Interactive 2019 with my friend Florent Vilmart.

Visual Studio Code is a text editor that has become very popular. A reason for such fame is Extensions. You can pick and install just the ones that fit your needs. You can customize VS Code to be super-productive. That’s cool.

But have you ever considered going further, and build your own VS Code Extension?

In this hands-on, we show you how to create, configure, package and publish a VS Code Extension. You will understand how you can manipulate the structure of your code, using the Abstract Syntax Tree (AST). With this, you’ll build your first VS Code Extension that will perform your own, custom, automated refactorings.

You can follow the workshop using this repository: nicoespeon/talk-build-your-first-vscode-extension.

Following up this workshop, I’d advise you to try Abracadabra. It’s an open-source VS Code extension I’m building to perform intuitive, automated refactorings for you, in JS and TS.

I recommend you to install it, use it and maybe help me by contributing 😉

TIL: How to stabilize a cutting board

Tue, 10 Dec 2019 00:00:00 GMT

Another cooking trick today 👨‍🍳

Maybe you’re like me and you have a very basic, yet efficient cutting board.

If so, you might struggle as well to stabilize it when you cut food. It might even have little rubber feet to prevent it from moving, but it’s not always very efficient.

A few months ago, I did a cooking class with my wife at Ateliers et Saveurs, in Montréal. They taught us a very simple trick to make sure the cutting board won’t move at all.

Put 4 jar gaskets under your cutting board.

It’s very efficient. My simple cutting board is stable, so I can chop safely 🔪🥒

If you don’t already have some, you can easily find and buy these. They are usually cheap (~3$ CAD each).

And you, do you have tips & tricks for cooking? 😜

TIL: How to checkout to "previous" branch

Tue, 03 Dec 2019 00:00:00 GMT

Git is the kind of awesome tool that keeps giving. Ok, this feature is not as impressive as git worktree or the powerful reflog, but it’s very handy.

Say you’re on a branch. You checkout to master temporarily. Then, you want to come back to your branch. Wait… what’s the name of your branch again?

Turns out, you can just ask git to go back to the previous branch you were on with git checkout -.

It works like cd -: it checkouts the previous branch and if you run it twice, you’ll end up on the same branch you’re now.

And you, do you have any git trick? 😜

Find and fix performance issues of your VS Code Extension

Tue, 26 Nov 2019 00:00:00 GMT

I’m developing a VS Code Extension that provides intuitive automated refactorings in JavaScript and TypeScript. It’s called Abracadabra.

Recently, I looked for performance bottlenecks to make it faster. In this article, I’ll explain how I did that, so you can do the same.

How do you know you need to improve performances?

When I make things, I try to follow the mantra:

“Make it work, make it right, make it fast.”

— Kent Beck

Abracadabra is a side-project. I first developed the features I needed and shipped that. As I learned along the way, I kept refactoring the code to improve readability, thus maintainability. During this process, I took decisions I knew were a bit naive from a performance standpoint, but they simplify a lot the development. A few months after the first release, I had developed more than 20 automated refactorings. Today, it makes me much more productive when I code.

Most refactorings are exposed as VS Code Quick Fixes. Regarding where your cursor is, VS Code will tell you the relevant refactorings you can perform through the lightbulb 💡

To determine what are the relevant refactorings, Abracadabra naively tries to perform each of them. Each refactoring that could change the code would be considered relevant. Any time the cursor changes position, VS Code would ask Abracadabra the same question: what are the relevant refactorings on this code, from the current selection? Hence, any time the cursor changes position, Abracadabra recomputes all refactorings of the catalog, again.

That doesn’t sound very performant, does it?

Indeed, I thought about it at the beginning, 2 weeks after the very first release. However, it wasn’t needed at that time. At that time, despite the theory, I couldn’t feel performance issues from usage. Thus, the naive implementation was fine. It kept the code simple, allowing me to develop more and understand the problem better.

Improving performance implies writing less naive, harder to maintain code to make it fast enough for the users.

Improving performance is a tradeoff on code maintainability.

That’s why I think you shouldn’t improve performance without measuring it. Measure performance. That’s how you know if you need to improve it or if it’s good enough.

How to measure the performance of a VS Code Extension?

VS Code provides quite a good tooling to do so.

Show Running Extensions

The first thing you need to do is to debug your extension. You certainly want to measure performance before and after your changes. Debugging your extension opens an extension host that will compile your extension code, so you can run it live.

In the Extension Host, open the Palette (⌘ ⇧ P / Ctrl Shift P) and search for Show Running Extensions.

That will open a tab wich list your running extensions:

The first thing you can see from this tab is the Startup Activation time. It tells you the time each extension took to activate.

As a rule of thumb, if your extension takes more than 500ms to activate, there’s probably something you could do to speed that up—it’d be a good idea to bundle your extension if you don’t do that already.

If you’re below that, I’d say that’s OK. Around 100-200ms is great. Below is amazing 😉👍

Now, that was for startup activation time. But if you’re probably concerned with your extension runtime performance. So how can we track that?

Record Extension profile

On the top right, you have a series of icons that will allow you to record a performance profile of the extension at runtime.

Click on the record button (the dot in the circle). It will turn red, meaning it’s recording.

Then, go back to your code. Trigger your extension. In the case of Abracadabra, I was suspecting performance issues on Quick Fixes, so I moved my cursor around the code, to trigger Quick Fixes.

When you’re done, go back to the Running Extension tab and stop the recording. Then, click on the most-left icon to download the .cpuprofile you just recorded.

This CPU profile can be loaded in some DevTools. You can use the DevTools available in VS Code! Open the Palette again, and search for Toggle Developer Tools.

If you’re familiar with Chrome DevTools, well, it’s the same. Open the JavaScript Profiler tab. This one is hidden: you need to reach for the 3 dots menu → More tools → JavaScript Profiler.

From there, you can start profiling JS—but we already did that using VS Code Running Extension. You also have a Load button you can use to load your .cpuprofile.

Note: on Mac OS, if your finder doesn’t show all file extensions, it might save the file as .cpuprofile.txt and you won’t notice. If you can’t it that in DevTools, use the terminal to rename it with the proper extension (remove the .txt part).

Analyze the profile

I prefer to use the Flame Chart, it’s much more visual.

I’ll suppose you know how to interpret Flame Charts.

From this specific one, we can see 2 things:

The extension parse() the code repeatedly, which adds up and takes a lot of time in the end.
It runs one provideCodeActions() per refactoring, which could also be optimized.

That’s even clearer if we zoom in a bit:

So I went back to the code and optimized for that.

I parsed the code only once, then gave the AST to all refactorings. Then, I collected the list of available refactorings and provided them to VS Code only once. Here’s the same profiling, after the changes:

Much. Better. 😘👌

Anecdote: optimizing for performance makes code less intuitive

As you can see, profiling Abracadabra made me confident the problem was essentially due to every individual refactoring reparsing the same code. This was naive and I optimized so the code is now only parsed once.

But when I did so, I created issues that didn’t exist before! I had to tackle them.

Indeed, all refactorings now share the reference to the same AST. If one refactoring were to modify that reference, that would cause problems to the others. Cloning the AST could sound like a solution. I actually tried that and measure the performances after. It was worse. In fact, cloning the AST between each refactoring was more expensive than parsing the code each time.

That’s the heart of performance optimization: don’t guess, measure. Sometimes you’ll guess right. Sometimes, you won’t.

The actual fix was to ensure each refactoring wouldn’t mutate the AST when running for Quick Fixes. I had to introduce a bit more complexity in the code to optimize it. That’s usually the case when you optimize for performances. That’s why I follow Kent Beck’s mantra. If the code is simple enough, it’s easy to tweak it where necessary, for performance reasons.

Oh and a useful tip: when you do that, leave a comment to explain why this part of the code is not simpler. Your future-self and colleagues will thank you.

Conclusion

If you’re developing a VS Code Extension, I hope this guide would have helped you to find and fix performance issues.

If you have a problem with your VS Code performances in general, I suggest you read their wiki page on performance issues,

If you’re using VS Code to code in JavaScript or TypeScript, I can only recommend you give a try to Abracadabra. I craft these automated refactorings so they are useful and quick to use. It should save you a lot of time every day. It does for me 🙂

Finally, I wish I made you think twice about handling performance issues. Make it work, make it right, make it fast. What do you think?

How I used VS Code for my talk instead of Keynote or Powerpoint

Sun, 17 Nov 2019 00:00:00 GMT

Last week, I spoke at Bulgaria PHP 2019. After the great feedback I got, a few people asked me about my “original delivery” of the talk. Indeed, instead of using a regular presentation tool, I did everything from my code editor: Visual Studio Code.

Here’s the why and how I did that, so I can just refer to it instead of repeating my explanations. Hopefully, it will inspire you to do the same. I really think this is a powerful format for technical talks.

TL;DR I made a VS Code Extension to help you do the same.
👉 It’s called Slides.

VS Code as a presentation tool. But, why?

Well, I got inspired by Kent C. Dodds’ talk on “Managing an Open Source Project”. I read the original blog post from André Staltz and I liked it a lot. I recommend you to read it, but here’s my recap:

What really matters in a technical talk, is the content. Using your code editor really helps focus on what matters. You don’t go fancy on animations and all, you deliver the content.
When you explain technical concepts with code, it’s better to show that in action. Live-code it from a blank file. Show people there’s no black magic and what you say actually works.
It helps people understand your message. It really just feels like you’re showing a colleague how to do something.
If you want to show code, it’s even better to stay in your code editor than switching from a presentation tool.
You can still show images if you need to.

My talk was about “The Secrets of Hexagonal Architecture”. I wanted people to understand what’s the universally true axiom behind a maintainable codebase, regardless of the language, the architecture or the tooling. Thus, I wanted to show the code. I needed to illustrate the theory with concrete, working examples.

That’s why I decided to use exclusively VS Code for this presentation. And it was great!

Now, I learned a few things along the way. If you want to do the same, I think it’d be helpful I share that with you 😉

How to build a great presentation with VS Code

Putting the theory aside, here’s my recipe to build a nice talk using VS Code only:

Raw content in Markdown files
Rich content through diagrams & drawings
Live-coding from executable, blank files
Use a non-fancy terminal to favor clarity
Make live-coding smooth
Don’t stay behind the computer the whole talk, use a clicker

Raw content in Markdown files

Focus on the content. Write this content in plain Markdown. Show that.

For your (great) content to be seen comfortably, it’s better to configure VS Code appropriately. Based on André Staltz’s advice, it’s better if you:

Use a light theme. Contrast is always better so people can read regardless of how dark is the room.
Use a big enough font size, so anyone can read from the back of the room.
Get rid of distractions. Hide the sidebars and everything. Just show the file content.

Rich content through diagrams and drawings

I talked about Hexagonal Architecture. It’s easier to understand the theory with some diagrams. In such a scenario, I don’t want to try my luck with ASCII art.

I draw my diagrams somewhere else (this can even be Keynote, whatever), and export an image. VS Code will show the image—so it’s just like a slide after all.

For this talk, I even decided to illustrate everything I said with hand drawings. Though, that’s personal and specific to this talk. That’s also because I had my slides ready from previous presentations of this talk 🤓

Live coding from executable, blank files

I name files in alphabetical order. For convenience, I use a counter as a prefix. So I go 01.md, 02.md, 03.jpg, etc.

When I want to live-code, I put an empty file in which I’ll code. For example 04.php or 04.js.

It’s better to leave the file empty. If it has content inside, it should be something the audience already knows for sure.

Since it’s just a regular file in my code editor, I can run the code from the terminal afterward. No black magic involved!

Use a non-fancy terminal to favor clarity

When it comes to the terminal, we, developers, can be very fancy. I bet yours is not configured like mine. We all adapt our tools to our specific needs and personal style. That’s fine!

However, this can be very distracting during the talk. I don’t want people to think about my git aliases or my shell theme. I want them to focus on the content of my talk.

Thus, I recommend getting rid of the fancy stuff during the presentation. A basic bash shell should be enough and won’t surprise anyone.

I also prefer to use VS Code embedded terminal, so I stay in my code editor—that’s why I don’t use Keynote after all. That way, I can configure it to use a non-fancy version of my terminal without changing the terminal I use every day!

Make live-coding smooth

Live-coding is a risky format for a presentation. Especially when you’re not used to doing it. It takes a lot of practice to be able to code confidently in front of an audience while keeping the talk entertaining.

You’ll write typos because your hands will be shaking off from stress. You will forget basic stuff because everyone will be looking at you. But most of all, you’ll probably break the connection with your audience when you start coding. That’s for 2 reasons:

You stop looking at them as you look at your computer. When you do that, you break the visual connection with people. Visual connection is important to deliver a great talk. Breaking it sometimes is fine, as long as you keep talking to them in the meantime. Problem is…
You stop talking too. At least, your flow is considerably slower. It’s filled with “hmmmmmm” as you’re thinking about the code you want to write and you can’t focus on talking at the same time.

When you’re looking at your computer, trying to remember what to type next, without saying meaningful information, that’s when people get bored and disconnect.

That’s why it takes practice. So you can keep a meaningful speech while you’re coding. Or you can look at your audience while you’re typing. Don’t underestimate how much preparation a decent live-coding requires! Coding in front of people, and making that interesting, is really hard.

Thus, you have 2 options:

Practice, practice, practice in front of people until you get comfortable enough.
Use the VS Code Hacker Typer extension. It allows you to record your live-coding in advance and replay that, in live.

But, that’s not live-coding anymore! What’s the point? Why not just showing code in slides then?

The main difference is the delivery.

In my talk, I wanted people to see the code being written, from a blank file, in the context of a code editor. When the code is written, I can run it. I think it’s best for understanding.

My typing skills matter less to attendees. While I replay the macro I saved, I’m able to focus my attention on my speech and keep the contact with my audience. What I say is more interesting, and connected with what people see appearing on the screen.

Of course, it still takes preparation and practice to make it smooth.

You may not like the idea, and that’s fine. I think what matters is the content of the talk and the delivery. And this really helps deliver great content to people.

Don’t stay behind the computer the whole talk, use a clicker

I told you about how important it is to engage with the audience to make the talk entertaining.

While coding, you’re stuck behind the computer. That’s OK. But when you’re not coding, it’d be better if you could move out and get closer to the people. Don’t stay hidden, behind your computer stand. Engage with your audience.

To do so, you should be able to switch slides “remotely”. It’s smoother if you don’t have to come back to your computer every minute or so to go to the next slide. That’s what clickers are for!

But how can you use a clicker with VS Code? I mean, “slides” really are files open in different tabs. So how can your clicker make VS Code go to the next tab?

The answer is almost in the question. To do so, you need 2 things:

Define a shortcut in VS Code that will move to the next tab. The command is workbench.action.nextEditor and you can configure a keyboard shortcut for it.
Remap your clicker to match the shortcuts you’ve defined.

How to remap your clicker depends on your OS and your clicker. Being on MacOS, I used a tool named Karabiner-Elements to remap my clicker. I found this tutorial to remap a wireless presenter very helpful.

The settings I used

Based on André Staltz’s recommendation, here are the settings I typically use to ensure the previous points:

{
  "workbench.colorTheme": "GitHub Clean White",
  "workbench.colorCustomizations": {
    "editorCursor.background": "#ffffff",
    "editorCursor.foreground": "#0000bb",
    "editor.lineHighlightBackground": "#f0f0f0",
    "editor.selectionBackground": "#aaeeff"
  },
  "workbench.statusBar.visible": false,
  "workbench.activityBar.visible": false,
  "editor.minimap.enabled": false,
  "explorer.openEditors.visible": 0,
  "editor.renderWhitespace": "none",
  "editor.renderIndentGuides": false,
  "editor.fontFamily": "SF Mono",
  "terminal.integrated.fontFamily": "SF Mono",
  "editor.fontWeight": "600",
  "editor.fontSize": 24,
  "terminal.integrated.fontWeight": "800",
  "terminal.integrated.fontSize": 28,
  "terminal.integrated.shell.linux": "/bin/bash",
  "terminal.integrated.shell.osx": "/bin/bash",
  "editor.formatOnSave": false,
  "workbench.editor.enablePreview": false
}

I installed the GitHub Clean White theme and the SF Mono because it will look like GitHub, and developers are likely used to that theme. That’s readable and less distractive than a fancy theme or font.

At the beginning of the talk, I go to the back of the room to check the font size. I adapt it so it’s comfortable to read from the back.

Automate most of the process with an extension

If we recap, at the beginning of my talk I need to:

Update my VS Code settings
Configure the shortcuts so I can switch between slides
Open all files, in order

At the end of the talk, I usually get rid of that because it’s not convenient when I work on the talk, on my computer. This is, the “slides” mode if you will.

Because I don’t want to manually do the back and forth, I automated that in an extension, and I published it. It’s called Slides and you can try it yourself.

Slides make it convenient for you to use VS Code as a presentation tool. You can toggle “slides” mode. It will adapt your settings for presentation and open your slides in a single shortcut. It allows you to navigate between your slides. Finally, you can exit “slides” mode when you’re done.

What do you think? Will you use VS Code for your next talk? If not, what’s holding you back?

5 refactorings I use every day

Sun, 03 Nov 2019 00:00:00 GMT

Hello there 👋

Refactoring code. Changing the way code is written, without breaking it. This is something I do constantly. I do it for many reasons, usually as preparatory work for further changes.

Today, I want to share with you the refactorings I use every day!

Because I apply these refactorings so often, I need them to be fast and reliable. Being a VS Code user, I developed an Extension to automate the refactorings for me, in an intuitive way. I called this extension Abracadabra. The following examples will use the extension to illustrate, but refactorings can be done by hand too, regardless of the language you’re working with.

Extract Variable

This is certainly the most frequent refactoring I do! Extract things into variables allows me to name the concepts and make the code easier to read.

When concepts are named, they can be reused. This is a solution to prevent logic duplication.

To extract any variable, I put my cursor on the variable and hit Abracadabra default shortcut: ⌘ ⌥ V (Ctrl Alt V if you’re not on Mac).

Since it works wherever my cursor is inside the variable I want to extract, it’s quite convenient to use. I simply have to think about extracting this thing into a variable, and here I am, naming this.

It also detects when there are multiple occurrences, so I can remove the duplication in the same shot!

Inline Variable

The opposite refactoring. They go in pairs.

Sometimes, a variable is not reused and its name doesn’t bring much value. If I can’t find a better name, then inlining it is an option I’d consider.

The typical scenario is temporary, intermediate variables. They often have poor names. They might have been valid before, but after some other refactorings they have become unnecessary and they just add noise.

In that situation, I put my cursor somewhere in the variable I want to inline. Then I press ⌘ ⌥ N (Ctrl Alt N if not on a Mac) and it gets inlined for me:

Rename Symbol

This one is a classic.

Actually, it’s a first-class refactoring in VS Code. The editor does it pretty well: I simply put my cursor on a symbol (like a variable name) and press F2. That makes me enter “rename mode”. Enter a better name, press enter and the editor will rename all references to that symbol.

It’s faster and more reliable than renaming using search and replace.

Convert To Template Literal

This one is specific to JavaScript.

So, it turns out I frequently need to convert a regular string into a template, so I can put variables in it. However, I find the backtick symbol a bit annoying to use with my keyboard—which is a bépo one, optimized for the French language. I need to press the key twice to enter the symbol, otherwise, it might merge it with the next letter. Thus, I’m glad I can trigger the conversion with a simple shortcut!

With Abracadabra, whenever my cursor is on a string, VS Code shows me a little bulb icon 💡. That’s a Code Action, commonly known as “Quick Fix”. It works because Abracadabra detects that a refactoring can be made here. The Quick Fix is a shortcut to execute that refactoring!

I recommend you to put a shortcut that’s easy for you to trigger Quick Fixes, so you don’t have to aim and click on the lightbulb. To do so, look for the editor.action.quickFix command in your VS Code keycap configuration. I put ⌥ Enter because I was used to this shortcut with Webstorm. The habits stuck when I moved to VS Code.

By the way: it also works on any part of a concatenated string. This is useful when I update some old code that didn’t use template strings.

Remove Redundant Else

Finally, I use this refactoring when I want to unnest some code logic, to make it more readable. I prefer to use guard clauses instead of nested conditionals.

Again, as a lot of Abracadabra refactorings, it’s a Quick Fix. This is nice because I only have to care about it when I can perform this refactoring. Looking at a piece of code, the extension tells me what refactorings can be executed. Less cognitive load for me.

What refactorings do you use every day?

That’s it. These are the 5 refactorings I use the most.

Through these, I wish I was able to illustrate why I developed Abracadabra and how it serves me every day!

What about you? Do you refactor often? What are the refactorings you do frequently? Did you learn something from this post? Let me know!

Introducing a refactoring tool for VS Code

Sat, 13 Jul 2019 00:00:00 GMT

I use VS Code every day. I use it exclusively since February 2018, both personally and professionally. I like it a lot.

But I am frustrated.

I am frustrated because I miss a great tool to perform automated refactorings for me. And neither VS Code, neither existing extensions provide the experience I’m looking for!

Thus, 2 months ago, I decided to follow my own advice and hack my own problem. I started creating the VS Code extension I was looking for. This extension analyzes my code, suggests refactorings and executes them with the minimal amount of keystrokes needed.

It helps me focus on my intention instead of manually following the scripted mechanics of a refactoring.

I called this extension: Abracadabra ✨

Why wasn’t I satisfied with VS Code refactorings?

It’s true that VS Code ships with basic refactoring operations. So what’s wrong?

Well, speaking from a personal point of view, few things aren’t great:

I need more than that. There are a lot of automated refactorings that I know and aren’t proposed.
I can’t just have the cursor on a variable and trigger an extraction. To get an appropriate suggestion requires selecting exactly the code to refactor. I need to select the whole extracted statement first, which is slowing me down.
I don’t like the UX much. Talking about extraction, I often feel confused in front of all the suggested options. I need to play the computer in my head and decipher what “enclosing scope” vs. “module scope” means in terms of the resulting code. I know that there is a better way.

I understand what it means, but it takes precious seconds to process. Don't make me think!

Before using VS Code exclusively, I used Webstorm professionally for a few years. And I prefer VS Code: it’s free, feels lighter to use and has a very active community.

But there is one thing Webstorm nailed that VS Code doesn’t provide: many, intuitive, automated refactorings.

This made me so productive back in the days. I relied on my editor to move fast 🏇

And I think it matters. If refactoring code takes 2 keystrokes I’m very likely to do it. If I have to find the correct combination of 5 keystrokes to make it work, I’m less likely. If I have to do it by hand… You get the idea.

Great automated refactorings are a productivity boost for every developer.

But wait, wasn’t there an extension already?

Yes! And I used it for some time.

I essentially work with JavaScript (and TypeScript). If you search for “JS refactoring” on VS Code Marketplace, you’ll find a promising extension called “JS Refactor”:

I appreciate the good efforts that were put in it. At least someone worked to provide more refactorings, shared that for free and maintained it 👏👏

But at this point, it was not exactly what I needed, for a few reasons:

I needed more refactorings operations. I’d consider operations like “Add Export”, “Negate Expression” or “Wrap Selection” not being “refactorings”. Even if they’re handy, they modify code behavior.
Also, sometimes, it didn’t work well. It had some hiccups working on classes or on TypeScript.
It handles partial selection better than VS Code, but it was still not as smooth as I was looking for. The UX was not the one I expected.

At that point, the best move for me would have been:

OK, maybe I can contribute and improve it!

Heading to the repository, I was really happy to see it seemed well tested 👍

But I felt the architecture was not quite what I’d have in mind. I’d have done abstractions differently…

Now, I’m not saying this is bad and I know better. Actually, I think the code is quite clean and well tested. But I started imagining how I’d build such solution, and I had this desire to make it happen. In fact, it would be a great opportunity for me to work on something where I could try things, fast, to scratch my own itch.

Sure, building another extension is not the best idea, community wise. For the greater good, I should have reached the author of the existing extension and see how could I help. And, at some point, I’ll probably ping him to see how I could help, now that I’ve a clearer idea of how all of this could work.

But for the moment, I wanted to build something on my own. Not to replace the existing extension, but to try something different. Something aligned with what I needed. Without having to deal with existing code and users.

Abracadabra!

That’s why, 2 months ago, I started to build this extension.

My goal is essentially to build the tool I’m missing.

There is a very cool side-effect of this: the learning part. Digging into Abstract Syntax Trees manipulations is super interesting. Also, I’m discovering how to build a VS Code extension for the first time. Finally, it’s a playground for me to test architectural decisions and practices, like documenting architectural decisions through ADRs.

I implemented a couple of refactorings across these 2 months. I published the extension a few days ago on the Marketplace.

Now I’m waiting for feedback to improve these first refactorings, fix edge cases and improve the UX to match what I’d expect from a great extension!

What about you?

Well first, if you do JavaScript or TypeScript and you’re looking for great automated refactorings, you can give Abracadabra a try!

Then, if you want to help me, you can:

Give me your feedbacks on what you like and what you’d like to improve. Whether you find a bug, have a suggestion or just want to share something, have a look at existing issues or open a new one.
If you’d like to contribute, you can start with the “Good First Issues” I’ve listed. Any kind of contribution is welcomed 🙂
Spread the word so I can get more use-cases and more feedbacks to improve the extension!

That’s it. I’m really excited about this and happy to start spreading the word.

Now, I feel better.

Drawing Git Graphs in the Browser

Tue, 04 Jun 2019 00:00:00 GMT

In this talk I presented a side-project that I’ve been developing with my friend Fabien Bernard since 2013: GitGraph.js 🎉

It’s a JS library that allows you to draw git graphs in the browser. Very handy to prepare presentations or write blog posts. Creating and updating those git illustrations becomes easy!

I already wrote about GitGraph.js in the past.

If there is one thing you should retain from my talk, it’s that you can hack your own problems. You certainly have this crazy idea in mind, that problem you want to solve for yourself… Stop waiting the perfect moment, just start doing it. Good things will happen!

Click on the following image to access the slides:

The project is available on GitHub: https://github.com/nicoespeon/gitgraph.js/

Different libraries are available:

@gitgraph/js for the vanilla JS version
@gitgraph/react for the React version
There is a browser bundle you can use directly in the browser 💪

If you want to play with the GitGraph.js, have a look at the online playground:

See the Pen @gitgraph/js playground by Nicolas Carlo (@nicoespeon) on CodePen.

The Secrets of Hexagonal Architecture

Tue, 12 Mar 2019 00:00:00 GMT

If there is one thing you should retain from my talk, it’s that you should separate the Domain from the Infrastructure if you want to write maintainable software.

Giving the talk at ConFoo Montréal 2019.

The Domain is the business part. Today, I work at Busbud. We sell intercity bus tickets, worldwide. We talk about things like Seat, Departure, Leg, Stop, Roundtrip… These are specific to our business, and we understand this vocabulary in a given context. We also have Taxes, Fees, Discount Code that you probably have to. This is a more generic Domain for us, but it’s still business.

The Infrastructure part is how is our current solution made. Fastly, Postgres databases, Redis instances, Express server, React… All of these technologies we use to provide busbud.com to travellers across the planet. But we could change the infrastructure, still we do the same business.

The Hexagonal Architecture is the simplest way to do this separation. Put your Domain at the heart of your software. Make your Infra depends on your Domain, and your Domain not depending on your Infra. Use business vocabulary inside the Domain part, to define intention-revealing interfaces (aka Ports). Build concrete implementations of these interfaces in your Infra (aka Adapters). That gives you the flexibility to plug any adapter to your domain.

It makes testing easy. It allows you to start with something simple, and evolve the infrastructure when actually needed. Finally, It’s a good first step towards Clean Architecture.

Here are the slides of the talk:

The Secrets of Hexagonal Architecture de Nicolas Carlo

I also gave that talk at Bulgaria PHP 2019, and it was recorded:

TIL: Tools can limit the potential of agile ceremonies

Fri, 18 Jan 2019 00:00:00 GMT

Today is Friday. And not any Friday, but the end of our 2-weeks Sprint. End of the Sprint means demos, but also a ceremony that I really like: Sprint Retrospective.

Whatever is your process, the core thing of Agile is to reduce the feedback loop. Having a recurring ceremony when people pause and reflect on how things went during the last few days is really valuable. It gives time to all of us to share our thoughts and feelings. We give feedback to others about how we operate as a team, and how we could do better. As the team grows in maturity, this feedback will be part of daily work. Still, having a recurring ceremony is really valuable as it helps us to step back and reflect.

At Busbud, we usually do retrospective using an online board. It’s a typical “Start, Stop, Continue” (SSC) board, with a column for “Next Actions”. I think the best part of it is that people can participate, even when they are not at the office—it’s really common for us to work from home when we need to.

But today was different!

Today, the meeting room was taken for unexpected, important reasons. So we didn’t have a place to regroup. That’s when I suggested to do the retrospective offline—nobody was remote anyway.

So we went to our big whiteboard. We bring the post-its, the markers and we stood up in half-circle around the whiteboard. We did a SSC and even a Mood Meter roundtable.

It. Was. Effective.

I remember retrospective meetings where we usually meet around a table. We’ll bring our laptops because, you know, we need to put our items in the online board. And I always get this feeling at some point that it’s more about the process than the content. We usually get some discussions, but it’s always the same people talking—me, definitely included.

Being all here, standing up and writing on post-its was much more engaging! Everybody was clearly involved in the retrospective. Everybody was here and present. We had really insightful exchanges, and we took very interesting “Next Actions”. I asked for feedback at the end of the session, and the team quite liked the offline format.

Sometimes, convenient tools can play against the meaning of the ceremony. Dropping the tool turned to unleash the potential of our retrospective. I have this feeling we may have found a better way of working, as a team. I’m looking forward in 2 weeks, to see how it goes.

And you, are you using an online tool for your retrospectives?

TIL: Easy file sharing from the command line

Wed, 16 Jan 2019 00:00:00 GMT

Today, I was working on Busbud “Preview” environment. I was connected to the distant Heroku machine, through ssh (with the Heroku CLI command heroku run bash). I ran a task that generates a CSV report and I wanted to get it on my local machine so I can read it more conveniently.

In such a scenario, I usually use scp from my machine to download the file from the distant server. But I didn’t know the address of the machine I was connected to since I used the convenient Heroku CLI. I could have searched for it, but instead, a Google search gave me a nice solution: transfer.sh.

Easy file sharing from the command line

— Transfer.sh website

The idea is to send data to this service from CLI, then retrieve it from an URL. Data could also be encrypted, and upload is made through https 🔐

Usage is very simple. Say I want to get my task-report.csv:

curl --upload-file ./task-report.csv https://transfer.sh/my-report.csv

After the upload is complete, I get the URL where I can retrieve it (e.g. https://transfer.sh/66nb8/my-report.csv).

Data are stored 14 days by default. But this can be configured on upload, with other different options like:

curl -H "Max-Downloads: 1" -H "Max-Days: 5" --upload-file ./hello.txt https://transfer.sh/hello.txt

I can also configure an alias for convenience, but I didn’t feel I need to—I’d usually use that from a distant server which I don’t have the address on hand.

So yeah. I did that and got my CSV file in no time. Thank you transfer.sh!

And you, do you have tips & tricks for retrieving distant files?

TIL: A parchment paper trick

Tue, 15 Jan 2019 00:00:00 GMT

Today aha moment is cooking related 👨‍🍳

I usually use parchment paper to protect baking sheets and the like—essentially when I bake cakes, cookies, and other niceties 🍪

Sometimes, I also struggle to make it fit the recipient. Especially when it goes 3D. I used to measure and cut to adapt. But overall, it’s not really convenient.

Making the paper fits the recipient properly can be painful. Credits The Pioneer Woman.

Today, I learned that you can actually wet the parchment paper and crumple it to make this easy! Parchment paper is strong, even when it’s wet. Crumple it, put it under water, press it to eliminate the excess of water then unfold it. It will be easier to make it fit the recipient you want to protect.

Also, I learned that you can use it almost any time a recipe tells you to put some butter on your cake mold. Wet parchment paper will do the trick faster and leave the mold in a cleaner state—so you can reuse more quickly if you need to.

And voilà!

Credits Alton Brown.

And you, do you have tips & tricks for cooking?

TIL: How to start a talk

Mon, 14 Jan 2019 00:00:00 GMT

2019 is a challenging year for me. I’ll give my first talk, in English, in front of a larger audience than the 40-folks standard of local meetups I’m used to.

Actually, I’ll give two talks:

In March, I’ll present “The secrets of Hexagonal Architecture” at Confoo Montreal
In May, I’ll talk about “Drawing Git Graphs in the browser” at FullStack NYC

I did quite a few talks in the past, but they usually were in French – my native language – and in front of the local tech community, in meetups. As you might imagine, I’m both thrilled and scared. Thus, I’m preparing these talks – the last thing I want would be to screw up in front of hundreds of people I don’t know 😅

I already have plenty of good resources about giving such talks and preparing great slides. In fact, I used to provide such advice when I was coaching colleagues to speak at meetups, back in Paris.

But today, I came across a short video titled “How to Start a Speech”. The fact it’s a 9min video is great: it goes to the point. I watched it after lunchtime, and it was both catchy and insightful. Here’s what I learned.

There are 2 common mistakes speakers usually do when they start their talk:

A very formal talk introduction: “My name is Nicolas Carlo, I work at Busbud, today I’m gonna talk about ‘The secrets of Hexagonal Architecture’”. All of this, people already know – they do have a program. As I’m spending time repeating this information, it gives the audience time to disconnect from me and look at their phone while I’m going through usual stuff.
A very hesitating introduction: “Aaaaaah eeeeeeeeeh… Is the mic working?… Yes… Ok… Right… hmmmm…”. Which is obviously not very engaging. It could happen though because of stress. My personal advice here is to practice the talk before – in front of colleagues at work, or/and in a local meetup. Practicing out loud at home and recording the video is also really helpful to self-improve our talk delivery.

The second one is obvious, but I didn’t think too much about the first one. It’s obviously the classical way of doing it, and most of the speakers I know do it like that – including myself.

Then, here are 3 better ways to start a talk:

🤔 Ask a question that matters to the audience. The idea is to make people relate to the problem. If I raise a question that you also have at work, it’s likely you’ll be interested in knowing the answer. The talk is here to answer that question.
🙀 Start with a fact that shocks. It’s really easy today to access facts, studies, and different resources. A fact can illustrate the whole point of the talk, or be somehow related. Having a powerful fact that will force the audience into rethinking what they know is really catchy.
📖 Tell a story. Actually, it’s not something new. Still, it holds true. Even more for conferences talks. “Once upon a time” makes children lean forward. And the grown-up way of saying “Once upon a time” is to tell a story, usually one from your own life. A story that connects you to the subject of the talk. A story that explains why it is important to you. For example, “the first time” you discover the benefits of the thing you’re presenting.

That’s it. I’ll personally try to rework the introduction of my Confoo talk to start with a story – which is not that hard, I do have a story and fun facts to tell about it!

Here’s the full video if you have some more time to watch it. In my opinion, it worth it:

And you, do you have tips & tricks for public speaking?

"I need to change this code, but it has no test"

Sat, 12 Jan 2019 00:00:00 GMT

Here’s the deal: you need to change the code to make this awesome new feature work, but that code is not covered by an automated test. How do you know you didn’t break anything when you’re done?

That’s a typical scenario I frequently face.

I see different approaches in such a situation:

🤞 Cross fingers, do the change and hope nothing breaks. Manually test different use cases you know. After all, you’re just adding a feature. You know the codebase, more or less. What could go wrong?
🤔 Spend time to understand, test and refactor the code before changing it. “Make the change easy, then make the easy change”. Sure, it will take some time. You didn’t estimate that task to take that much time actually. That’s unexpected complexity. But, in the end, you will leave codebase in a better state and you’ll be able to go faster.
📸 Take a snapshot of existing code behavior. Consider it a black box and capture enough of its behavior to feel confident touching it.

I clearly think the first approach is shooting yourself in the foot − except if you know you won’t need to maintain that code. Heck, it seems you’re maintaining this code already, otherwise, you wouldn’t have this question in the first place! If you want to keep moving fast without breaking everything, there is a better, more professional way.

The second approach would be ideal. Working effectively with legacy code requires putting the existing code into a test harness, first. Then, you can refactor. But, it takes skills to write good tests. You should practice these skills though, they will help you with these – so common – scenarios. Now, I hear you: client demo is next week and you need to ship that cool feature before. You need a pragmatic solution to the problem. You’re gonna take this shortcut consciously so you can deliver, then you’ll pay the technical debt back. Now, are you stuck with approach #1 then?

Nope. Approach #3 is more… pragmatic. You have to put your code under test before you touch it anyway. But, who said you need to completely understand current code to do so? What you want is to know if you break existing behavior when you touch the code. This, you can do with Approval Testing.

The main idea is:

take a snapshot of existing code behavior, in all possible variations
use test coverage to discover parts of the code not covered with the variations
use mutations to ensure you detect any broken behavior

You don’t need to understand existing code to do so. That’s the good news.

There is a pre-requisite though: you need to take a snapshot of your code behavior, meaning that you should be able to stringify the output of your code, including side-effects. If your codebase was not designed with tests in mind, you probably need to rely on Michael Feather’s book to help you get started.

Now, let see how you can do that in JavaScript.

Approval Testing in JavaScript

My personal go-to for JavaScript testing nowadays is Jest.

It is simple to set up – almost no configuration needed. It has a wonderful test runner baked in, with a powerful watch mode. Finally, and that’s what you’re looking for, it can take snapshots.

Jest runner in action – damn it's so cool!

Snapshots are powerful. But they are a test-after technique. I usually recommend to practice Test-Driven Developement, so you should barely need snapshots. Actually, snapshots have very few valid use-cases. Putting tests on existing code, before refactoring it, is one of these.

Now, I need an example. I’ll use the Gilded Rose kata to illustrate that. It’s an exercise to practice refactoring techniques, which is really convenient here. I made a JS starter of the kata that you can use.

So you have 2 classes: Shop and Item. Item is pretty simple:

export class Item {
  constructor(name, sellIn, quality) {
    this.name = name
    this.sellIn = sellIn
    this.quality = quality
  }
}

Then you have Shop which takes a list of items and have a method updateQuality() that will update the quality and sellIn attributes of every item. There is a bunch of logic that’s currently supposed to work. It is not pretty though, so I won’t put it here but give you a link to the beast instead.

Your goal: change updateQuality() so it deals with "Conjured" items too (they degrade in quality twice as fast as normal items).

There is no test. A good idea is to refactor this code first – make the change easy, remember?

Let me show you how to apply the Approval Testing technique in such a scenario.

1. Generate an output you can snapshot

The first step is to generate a snapshot from updateQuality(). It doesn’t return a string, but it changes items. Thus, my first move is to write a function returning something which captures the changes so Jest can take a snapshot of it:

// I put that code in my test file, since it's test-related.

function doUpdateQuality(name, sellIn, quality) {
  const gildedRose = new Shop([new Item(name, sellIn, quality)])
  const items = gildedRose.updateQuality()
  return items[0]
}

I could have returned items, but I’m simplifying things a bit here: I’m only testing a shop with one item. That’s because I already know the behavior is the same regardless the number of items. It might not be your case. You should adapt to your situation, this is the tricky part.

Now I have a doUpdateQuality(name, sellIn, quality) I can call from my tests. It will instantiate the shop, call the method I’m testing and return me the updated item.

My next move is to write the first test, taking a snapshot from the output:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
})

function doUpdateQuality(name, sellIn, quality) {
  // …
}

If you’re not familiar with Jest snapshot testing, I suggest you take a few minutes to have a look at their documentation. I will wait 😉

2. Using test coverage to find all input combinations

At this point, I generated a first snapshot, given a set of parameters. Jest will tell me if any regression happens to that scenario. Can I go refactor updateQuality() now? Nope. Because I’m not covering all the code with this snapshot. This, I can know thanks to the test coverage!

To generate test coverage, I run Jest with the --coverage option.

I find the html report to be the best in this scenario. To do so, I need to configure Jest options. This can be done in a config file, or quickly in package.json:

{
  "name": "gilded-rose-kata",
  // …
  "scripts": {
    "test": "jest"
  },
  "jest": {
    "coverageReporters": [
      "html"
      // I could add "text" or "text-summary" to see output in the console
    ]
  }
}

Then, I run yarn test --coverage (or npm run test -- --coverage), which generates a coverage/ folder.

I open the coverage/index.html file:

All the red lines, I don’t test.

Test coverage can only tell you
what code is not tested, nothing else.

Let’s figure out another combination that would cover more lines… An item with a positive quality should do:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 1)).toMatchSnapshot()
})

I run the test again. A new snapshot is generated.

Coverage report is updated:

Yay, less red lines!

So you get the idea: during this phase, I need to find all the possible combinations that would cover all the code. No more red lines.

Let’s fast-forward a bit. Here’s what I’ve got:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 2)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 1)).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 1)
  ).toMatchSnapshot()
})

No more red lines, but I still have these E symbols. These symbols mean that I’m covering the if case, but I’m missing the else clause – that’s why only 68.57% of branches are covered. I need to cover them too:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 2)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 50)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', -1, 1)).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 11, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 49)
  ).toMatchSnapshot()
})

So far, so good. I’m covering every line and branch. Can I go refactor updateQuality() now?

Well… not yet. Remember when I said test coverage can only tell you “what code is not tested”? That means it doesn’t tell you if the covered code is properly tested.

This is why setting a test coverage objective to ensure test quality doesn’t work. Test coverage tells you parts that are not tested – and that might be fine not to test these parts. Other than that, it says nothing.

To me, good test coverage comes as a side-effect of a good testing strategy (TDD). It’s not a target.

3. Use mutations to verify snapshots

To ensure the covered code is actually tested, I’m gonna introduce little mutations in the code.

The goal here is to see the test fail. If I change the existing code and a test fail, I’ll feel safe refactoring this code! When the test has failed, I revert the mutation and move to another line.

What mutations should you introduce? Again, it depends on what you’re testing – sorry. Usually, mutate the side-effects that you’re capturing in your snapshot. In my case, that means I don’t have to change ifs, but only the updates to item. There are 8 of them.

Let’s start with the first assignment, line 22:

if (this.items[i].name != 'Sulfuras, Hand of Ragnaros') {
  this.items[i].quality = this.items[i].quality - 1
}

I’ll introduce a little mutation, just to check:

if (this.items[i].name != 'Sulfuras, Hand of Ragnaros') {
  this.items[i].quality = this.items[i].quality - 2
}

I run my tests again:

Great! I know my test will catch any regression here. I can revert my mutation.

Let’s move on the other ones. I introduce a similar mutation line 33:

if (this.items[i].quality < 50) {
  this.items[i].quality = this.items[i].quality + 2
}

Run tests again and…

That’s not good.

Before going further, I revert the mutation in the code. Don’t let mutations live long.

Then, at that point, I need to think a bit about the code – yeah, I lied, but you don’t have to understand all the code. How could this happen? I suspect that a further update makes me take another path in the following logic, resulting in a similar result with my given combinations. Looking at the lines of code I want to mutate, I find this one to be interesting:

if (this.items[i].name != 'Sulfuras, Hand of Ragnaros') {
  this.items[i].sellIn = this.items[i].sellIn - 1
}
if (this.items[i].sellIn < 0) {
  // …
}

That means if sellIn is 0, then it doesn’t execute the rest of the code. I try to add another combination:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 2)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 50)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', -1, 1)).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 11, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 49)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 1, 0)
  ).toMatchSnapshot()
})

I generate the new snapshot, then retry the mutation:

It worked!

I revert my mutation and continue to the next assignment. I do that until I know all of them are actually covered with tests.

Hopefully, I didn’t found other false positive for coverage. Here’s the final list of tests:

it('should update quality', () => {
  expect(doUpdateQuality('foo', 0, 0)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('foo', 0, 2)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Aged Brie', 0, 50)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', 0, 1)).toMatchSnapshot()
  expect(doUpdateQuality('Sulfuras, Hand of Ragnaros', -1, 1)).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 11, 1)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 0, 49)
  ).toMatchSnapshot()
  expect(
    doUpdateQuality('Backstage passes to a TAFKAL80ETC concert', 1, 0)
  ).toMatchSnapshot()
})

Can I go refactor updateQuality() now?

Yes! All the code is now covered by snapshots. A wrong move and I’ll automatically know that. I can now refactor the code without introducing bugs. Then I’ll add the feature 🤘

4. These tests are technical debt

If you apply this recipe, remember this: you accepted to take technical debt here. You traded well-written tests against snapshots of existing behavior to get a test harness faster so you can refactor.

Snapshots are powerful, but they don’t help you understand what the code is supposed to do. Once the code is refactored, you should pay the debt back: write proper, comprehensive tests on your clean code to replace your snapshots. If you do so, this part of the codebase will be easier to maintain in the future, and you’ll add new features faster.

Introducing jest-extended-snapshot

Looking at the resulting test code, I thought that was a lot of boilerplate code in a single it!

So I refactored it with a custom Jest matcher: toVerifyAllCombinations().

With it, the previous code could be written the following:

it('should update quality', () => {
  expect(doUpdateQuality).toVerifyAllCombinations(
    [
      'foo',
      'Aged Brie',
      'Backstage passes to a TAFKAL80ETC concert',
      'Sulfuras, Hand of Ragnaros',
    ],
    [-1, 0, 1, 11],
    [0, 1, 2, 49, 50]
  )
})

It will generate all possible combinations of the following arguments, call doUpdateQuality() with each and take a snapshot of all results.

I like it because it expresses the intention better: “current behavior should be preserved for all these scenarios”.

I extracted that into a library so you can use it too: jest-extended-snapshot 👹

Inspiration

I discovered Approval Testing thanks to Emily Bache. She made a very nice 20-min screencast where she runs a demo of this very example, in Java:

You can read more about Approval Testing on http://approvaltests.com/.

They have a library to do that in JS, with Mocha: https://github.com/approvals/Approvals.NodeJS

Hexagonal Architecture & Elixir

Mon, 07 Jan 2019 00:00:00 GMT

This is a talk I gave at the Montréal Elixir meetup of November 2018.

Let’s start from scratch and go beyond the buzzwords.

We’ll go together through these ideas to understand how you can improve the maintainability of your projects, either greenfield or legacy.

We’ll see how it can be achieved in Elixir to check if it goes along the philosophy of the language.

I built a tool to work with complicated Sass codebases

Wed, 12 Dec 2018 00:00:00 GMT

I currently work as a web developer at Busbud.

Part of our stack is the public website that you can see at https://www.busbud.com. The first commit of its source code was made on January 2011. Today is December 12th, 2018. It has been almost 8 years!

For 8 years, the codebase has been growing. Today, code is still constantly updated to add new features, adopt or remove experiments, fix bugs… As we work, we need to deal with existing, working, legacy code and ensure nothing breaks when we change it.

Today, I’d like to tell you about the styles part.

A lot of Sass files…

A choice has been made, long time ago, to use Sass as a pre-processor for our stylesheets.

This is great. It simplifies maintenance of styles thanks to variables, mixins and other niceties Sass brings to us.

Among the niceties, we do use @import a lot. It allows us to import partial files into others and compile them into a single CSS stylesheet. Again: this is great. It allows us to split styles into smaller chunks (convenient for development) and get a single stylesheet in the end (convenient for production).

But @import creates dependency relationships between Sass files. Today, we face issues of dependency graph management in a growing codebase. Now, I’m not talking about critical problems like circular dependencies − Sass does a great job dealing with that. I’m talking about understanding the dependency graph as a whole. It usually boils down to these questions:

In which final CSS will this style be compiled to?
Will this style be compiled into a CSS file where it’s not needed?
Is there any file not imported anymore?
Is there any (useless) duplicated import of the same partial?

These are tricky questions to answer when you have a lot of files.

The dependency graph of our codebase is not trivial. It started with a bunch of Sass files along Jade templates ; now we miss a clear architecture to maintain our styles with ease. Hopefully, we’ve identified this technical debt, and we’re taking actions to pay it back.

But, until then, we have to work with this complicated Sass codebase.

Now, to visualise what we’re working with, I realised we need a tool to turn on the light.

Turn on the light, please

I first went to sass-graph. It’s a library which computes the dependency graph of a Sass codebase. Unfortunately, it was only able to output some sort of graph in my terminal, or a JSON structure. But to answer rapidly previous questions, I needed something visual.

Thus, I decided to plug sass-graph with a rendering library:

sass-graph-viz

Draw a visual graph of Sass dependencies

The difference is that sass-graph-viz generates a visual graph of dependencies in the browser.

You can use it as a CLI tool, as illustrated in this gif (a demo of v1):

You can quickly try it out with npx: npx sass-graph-viz path/to/your/scss

Or, you can install it with npm: npm i -g sass-graph-viz

Then use it in your terminal:

$ sassgraphviz --help
  Usage: sassgraphviz [options] <target>

  Options:
    -e, --exclude-externals  Omit files that are not under given target
    -s, --simple             Generate a simpler visualization (not recommended for complex graphs)
    -p, --port <port>        Port to use [3000]
    -h, --help               Output usage information

  Examples:
    sassgraphviz assets/scss
    sassgraphviz .
    sassgraphviz main.scss
    sassgraphviz main.scss -s -e -p 3001

Alternatively, you can use the alias sgv if sassgraphviz is too cumbersome to type.

How is this built?

It’s merely a plug of something that generates the dependency graph (sass-graph) and a graph rendering library. It exposes a CLI for convenient usage, and uses the browser to render the graph.

For graph rendering, I first went for viz.js because the API was simple and the result looked great.

The core idea of sass-graph-viz is:

Expose a CLI command to get the path to the directory I want to parse
Delegates to sass-graph the generation of dependencies graph
Translate sass-graph’s Graph into my own Graph model
Delegates to viz.js the rendering of the Graph in the browser

Now you might wonder: what’s the point in parsing sass-graph outputs into another Graph model?

I’d say this is the heart of the lib. This is my domain. Now, it’s probably really thin and might feel useless, but I have a few arguments in favor of this choice:

The rendering lib doesn’t need all of the details sass-graph generates in its “Graph” modelling.
The “Graph” from sass-graph doesn’t quite fit the rendering lib expected format anyway. A parsing is necessary at some point.
Maybe I’ll swap sass-graph for another tool, if I found a better one. If so, I’d better not tie the rendering lib to sass-graph implementation.
I don’t know yet all the features I’ll need to implement with the rendered graph. I don’t want to be limited by sass-graph capacity.

I quickly got it working for simple structures with viz.js. It helped me set up the architecture of the solution, exposing a CLI command to generate the graph.

For example, running sass-graph-viz assets/scss/ would produce following result:

But my graphs are more complex than that!

Otherwise, I wouldn’t have needed this tool anyway.

I moved to more realistic examples, running the tool against the codebase I was working on. There I confirmed I needed a better rendering lib to handle complex graphs.

I found vis.js − yeah, the one-letter difference is subtle. The lib showcases very cool, interactive graphs and the API looked nice. It was the solution I was looking for!

As the graph generation, the domain and the rendering were independent, is was really just about plugging another rendering adapter. One that would do the rendering with vis.js.

I enhanced the CLI a bit so vis.js became the default rendering lib and viz.js would be opt-in (with the -s, --simple option). I also provided a shorthand alias, so I wouldn’t need to type sassgraphviz every time.

At that point, running sgv assets/scss/ on previous example would produce following graph:

Few things to say here:

Unlike previous graph, this one is interactive. You can zoom, select and move nodes, as showcased in demo gif.
We visually distinct regular Sass files (e.g. main.scss) from partials (e.g. _header.scss). Partials are meant to be imported. I thought the distinction would be interesting.

And here’s where the separation of the domain started to pay off: I realised that I could add features to my graph, so it would be more useful. Identifying partial files is not the role of sass-graph, nor the one of the rendering lib. This belongs to the domain I created here. That also means it can be unit tested really easily: no need to manipulate actual Sass files, nor to spy on the browser.

Features, I want moar!

From usage, I noticed few quirks that I fixed. I also identified (and implemented) useful features.

The first one is the ability to exclude “external files” from the rendered graph. By “external files” I mean files that are outside the scope of the target folder. For example, we do import some source files from Bootstrap package which lives in node_modules/ − which is probably not the best idea, but these things happen. As I certainly can’t change all of these Bootstrap Sass files, I’d prefer they don’t show up and clutter my graph. I want to think about what I can change.

So here it is: sgv -e assets/scss/ will omit these external nodes from the generated graph.

Another feature from sass-graph-viz is the ability to focus on a file only. It’s very handy to only see a subset of the Sass files, the ones that are linked to a specific file. Intuitively, sgv assets/scss/core.scss does the trick and focus on core.scss dependencies (parents and children) only.

The last feature I wanted to highlight is the guidance the tool can provide. After all, since it computes the dependency graph of my Sass files, it could certainly detect suspicious patterns. One I identified was “the orphan partial” pattern. An “orphan partial” is a partial file that doesn’t have a parent. Which is weird, as partials are meant to be imported. These are likely dead code we can remove. And it paid off: I was able to detect some of them in our codebase, and get rid of these unused files!

Typically, the tool would render suspicious nodes in red, like so:

This was fun

I had a great time building this little tool. So far, it was useful to understand the relationship between all of these Sass files. It might become useless when we’ll solve the root cause of this mess, but it’s a handy tool to work with a complicated Sass codebase.

I hope it might be useful to you, if you face such situation. If you do, let me know about it!

If you have any comment, I’ll be happy to reply here or directly on GitHub issues.

PS: If you’re into Hexagonal Architecture, what I described may sounds like ports & adapters. It is. Just, I didn’t made interfaces & the hexagon explicit yet (functions and types were simple enough to do so).

Git rebase onto

Thu, 19 Jul 2018 00:00:00 GMT

C’est jeudi.

Le Sprint M a commencé lundi, sous les applaudissements rituels qui ponctuent chaque daily standup. Le backlog de cette itération te semblait ambitieux, trop optimiste, plein à craquer. Une nouvelle montagne que l’équipe s’attelait à dépecer méthodiquement, morceau par morceau, pour former progressivement un nouveau tas dans la colonne “Done”. La montagne s’écoule à présent dans chaque colonne du flow. Chaque story affiche la tête de la personne − souvent un développeur − qui travaille actuellement dessus. Le tout forme une chaîne, les stories s’écoulent de gauche à droite, portées par les membres de l’équipe…

Comme des fourmis qui ramènent des provisions dans la fourmilière. Tu voudrais t’attarder sur cette métaphore, mais Ahmed te ramène à la réalité : « Pour la code review que tu m’as demandé : c’est bon si je te fais ça à 15 h ? J’ai pas vraiment de temps avant… »

Tu fronces les sourcils :

« Hmmmm j’veux bien mais ça m’embête un peu. La prochaine feature que je dois attaquer dépend de ces changements alors… Ça me bloque.

− J’comprends, mais je peux vraiment pas le faire avant. Et je voudrais pas faire ça à l’arrache non plus.

− OK, va pour 15 h !

− Et puis t’as qu’à commencer à partir de cette branche. Tu rebaseras après.

− Comment ça ?

− Ben t’as qu’à commencer à partir de cette branche. Tu crées une nouvelle branche à partir de celle-ci, et tu travailles dessus.

− Heuuuuu… Oui, mais non. Si je fais ça, je vais avoir tous les changements des 2 branches dans le diff de la PR. On va s’emmêler les pinceaux !

− Fais-moi confiance. Crée une nouvelle branche, travaille dessus et on verra toute à l’heure comment gérer ça.

− Si tu le dis… Merci. »

Tu te retournes vers ton écran pendant qu’Ahmed se dirige, le pas pressé, vers la salle de réunion, son ordinateur sous le bras. Tu hésites encore un peu.

Ma foi, tant pis.

Création de la branche `feat/dynamic-campaigns`

15 h 30. Tu reçois la notification qui t’annonce que ta PR a été approuvée. Un sentiment de satisfaction dessine un sourire sur ton visage. Au même moment, Ahmed fait rouler sa chaise jusqu’à ton poste.

« Legit to me. Beau boulot sur la feature, j’ai rien trouvé à redire, c’était limpide !

− C’était une petite PR aussi, ça aide.

− C’est sûr. En tout cas, tu peux merger.

− Yep, j’étais en train de le faire eeeeet… C’est fait !

− Top ! »

Alors qu’il s’apprête à faire rouler sa chaise dans le sens opposé, tu le rattrapes.

« Attends une minute. J’ai créé une branche comme tu m’as dit. J’ai commit dessus, mais maintenant elle part de l’autre branche, celle qui est mergée.

− C’est pas un problème. Faut que tu la rebase sur master.

− Et comment je fais ça s’il te plaît ?

− C’est pas sorcier tu vas voir. Montre-moi ton historique git pour commencer.

− Voilà. »

Historique git, `feat/dynamic-campaigns` partant de `feat/create-campaigns`

« Bon, tu vois le dernier commit de master ? C’est la branche que tu viens de merger. On applique une stratégie de “squash and merge”, donc ta feature devient un seul commit sur master.

− J’ai jamais trop compris pourquoi on faisait ça d’ailleurs…

− C’est un autre débat. Pour te la faire courte, certains préfèrent le côté unitaire de “1 commit = 1 feature”. En pratique, vu que nos branches sont assez courtes, ça passe. Et master est toujours stable.

− Mouais… M’enfin j’ai lu que c’était mieux de garder l’historique.

− Peut-être. En tout cas, c’est notre convention pour le moment. Si tu veux la challenger, propose le sujet pendant l’atelier tech, demain.

− OK.

− Bref, ce que tu veux faire toi, c’est prendre cette branche feat/dynamic-campaigns en vert, et la déplacer pour la faire partir de master.

− Hmmmmm… Oui c’est ça.

− Et pour ça, il va falloir utiliser git rebase. Il y a une option “onto” qui te permets de faire exactement ça.

− Genre “rebase onto master” ?

− Un truc comme ça oui, regarde. »

Rebase de la branche depuis l’ancien parent sur master

Perplexe, tu essaies de comprendre ce qu’il vient de se passer :

« Attends une minute, tu peux m’expliquer ?

− Bien sûr. La commande git rebase peut prendre un paramètre “onto” quand tu veux faire des choses un peu moins classiques. Et “onto” accepte 3 arguments.

− Le premier c’est master. C’est la branche d’arrivée ?

− Exact ! C’est la référence du nouveau parent de la branche que tu rebase. Ensuite, tu précises la référence de l’ancien parent de la branche en question : feat/create-campaigns dans ton cas.

− Mais, on ne l’avait pas merge celle-là ?

− Sur origin oui. En local, non. Rappelles-toi de ton historique git, tu as toujours cette branche-là sur ta machine.

− OK je vois. Donc nouveau parent, puis ancien parent…

− Et enfin, la référence de la branche que tu veux rebase. En pratique d’ailleurs, n’importe quelle référence de commit fonctionne. Mais généralement, on manipule les branches.

− C’est plus pratique.

− Ouais. D’ailleurs, le dernier argument est optionnel. Si tu ne le donnes pas, il prendra HEAD comme référence. Mais bon, je préfère être explicite, ça fait moins de surprises. »

Tu acquiesces tout en affichant à nouveau l’historique git pour visualiser le résultat :

Historique git après rebase de la branche

« Hé, ça a marché ! C’est comme si la branche était partie de master !

− C’était le but.

− Merci beaucoup ! Je vais noter l’astuce dans un coin.

− Tout le plaisir était pour moi ! »

Concluant sur cette tirade, Ahmed s’élance à nouveau pour tenter de rejoindre son bureau d’un seul coup. Raté. Pendant qu’il piétine pour rouler le dernier mètre qui le sépare de son poste, tu finis de nettoyer ta branche locale qui n’a plus vraiment de raison d’être.

Adieu.

Suppression de la branche `feat/create-campaigns`

Le sourire aux lèvres, tu jettes un coup d’œil à l’historique git.

Historique git final

C’est propre.

Tu regardes ta montre. 15 h 45. Tu ouvres à nouveau ton éditeur en te disant que tu as encore le temps d’avancer un peu.

Une story traitée de plus. Comme les fourmis…

Git rebase onto

Thu, 19 Jul 2018 00:00:00 GMT

Thursday.

Sprint M started this Monday, just after the usual round of applause that ends every daily standup. When you looked at the backlog, you found it a bit ambitious, too optimistic, greedy. A new mountain the team started to tear apart methodically, piece by piece, progressively stacking these pieces under the “Done” column. The mountain was now bleeding through each column of the flow. Each story shows the head of the person − usually a developer − currently working on it. The whole thing is a chain, stories flowing from left to right, carried by the members of the team…

Just like ants carry food to the anthill.

You’d like to think about the metaphor a bit longer, but Ahmed brings you back to reality: “About the code review you asked me: is it OK if I do it at 3? I don’t really have time before…”

You frown:

“Well, why not but it’s inconvenient for me. The new feature I need to work on depends on these changes so… I’m blocked now.”

“I get that, but I really can’t do that sooner. And I wouldn’t like to scamp it neither.”

“OK, go for 3pm!”

“Anyway, you are not blocked. Just start from the current branch. You’ll rebase later.”

“How’s that?”

“Well, just start from the current branch. You create a new branch from this one and you work on it.”

“Thanks but… no. Look, if I do that, the PR diff will contain changes from both branches. It’ll be a mess!”

“Trust me. Create a new branch, work on it and we’ll figure this out later together.”

“If you say so… Thanks.”

You turn back to your screen while Ahmed heads rapidly toward the meeting room with his laptop. You still hesitate.

Damn it. Let’s do that.

Creating `feat/dynamic-campaigns` branch

15:30. You get the notification telling your PR has been approved. Satisfaction makes you smile. In the same time, Ahmed rolls his chair to your desk.

“Legit to me. Nice job on this feature, nothing I could think of. Neat!”

“It was a small PR. It helps.”

“Sure. Anyway, you can merge it now.”

“Yup. I was just doing it aaaaaaaand… Done!”

“Great!”

As he’s about to roll in the opposite direction, you add:

“Wait a minute. I created a branch like you told me. I did a few commits on it. But now it’s starting from the other branch, the one I merged.”

“Not a problem. You need to rebase it on master.”

“And how am I supposed to do that?”

“It’s not a big deal. Let’s see. First, show me you git log.”

“There you go!”

Git history, `feat/dynamic-campaigns` starting from `feat/create-campaigns`

“See the last commit on master? This is the branch you merged. We use the “squash and merge” strategy, so your feature became a single commit on master.”

“I never get that part. Like, why are we doing that anyway?”

“This is another debate. In short, some prefers the fact that “1 commit = 1 feature”. Technically, because our branches are quite short-lived, it works. Thus, master is always stable.”

“Yeah… But I’ve read that it’s better to keep the actual history.”

“Maybe. Anyway, this is our convention for now. If you want to change it, go ahead and propose the subject during tomorrow’s tech meeting.”

“OK.”

“Back to what you want to do. You want to take the green branch feat/dynamic-campaigns and move it so it starts from master.”

“Hmmmm… yeah, that’s it.”

“To do that, you need to use git rebase. There is an option called “onto” which does exactly that.”

“Like rebase onto master?”

“Kind of. Look.”

Rebasing the branch from old parent onto master

Still a bit puzzled, you’re trying to figure out what just happen:

“Wait a minute. Can you explain?”

“Sure. You see, git rebase can have a parameter called “onto” which is useful in such scenarios. It takes 3 arguments.”

“So the first one is master. That’s the new branch, right?”

“Right! It’s the reference of the new parent for the what you’re rebasing. Then comes the reference of the old parent: feat/create-campaigns in this case.”

“But… Didn’t we merge this one before?”

“On origin yes. Locally on your computer, no. Remember your git history? You still have that branch on your machine.”

“OK, got it. So new parent, then old parent…”

“Then the reference of the branch you want to rebase. Technically, any commit reference will do. But usually, you work with branches.”

“It’s more convenient.”

“Yeah. The last argument is optional. If you don’t provide it, it’ll use HEAD as a reference. But, you know me, I like when things are explicit. Less surprises.”

You nod while displaying the new git history to visualize what you’ve done:

Git history after rebasing the branch

“Hey, it worked! It’s just like the branch started from master!”

“That’s what you asked for.”

“Thanks a lot! I’m gonna write this done somewhere.”

“My pleasure.”

On this final line, Ahmed pushes on his feet to roll back to his desk in a single attempt. Failed. As he tramples to finish rolling, you clean the local branch that has no more reason to be.

Bye.

Deleting `feat/create-campaigns` branch

You smile and give another look at the git history.

Final git history

Clean.

You look at your watch. 15:45. You open your editor thinking that you still have time to work a bit more on this.

Another story processed. Just like ants…

TDD with Elixir

Thu, 07 Jun 2018 00:00:00 GMT

This is a lightning talk I gave at the Montreal Elixir meetup of May 2018.

I’m quite new to Elixir. I love practicing Test Driven Development. I’ll share with you my findings, successes and pitfalls of doing TDD with Elixir.

Here are the slides:

So I went to Montreal Elixir meetup

Fri, 23 Mar 2018 00:00:00 GMT

Few days ago, I went to Montréal Elixir meetup of March.

I’m French. I moved to Montréal in February. Thus, this is the beginning of a new life for me ; a Canadian-dream as a Developer at Busbud. I used to attend / talk at / organize a lot of meetups, back in Paris. I’m now looking to meet the tech community of Montréal.

So here is my feedback about how this meetup was, and what you could expect from it.

By the way, if you don’t know it yet: Elixir is a dynamic, functional language.

It is built upon Erlang shoulders, which is really fault-tolerant and built for scalability (think telecoms). To put them in a nutshell, I’d say Elixir main goals are: productivity, maintainability and reliability.

Montréal Elixir is a monthly meetup. The community is not big − we were around 20 persons at the event.

They do have a website: http://www.montrealelixir.ca

The typical agenda of the meetup is:

Networking & food first, which is a nice ice-breaker.
Announcements from Elixir community, about books, news from the meetup organizers…
Talks, usually 20 minutes ones. But we’ll try some lightning talks (5min) in the future.
Sponsor talks & open mic to anyone who’d have something to share to the group

It starts at 18:30, ends at 20:00, which is great if you want to go back home early. People generally speak english there, so it’s more inclusive.

This meetup talk was from Pedro Medeiros on “Elixir formatter internals”.

In case you wonder, a formatter is a tool that aims to maintain a consistent style for your project. Thus, you don’t loose time discussing whether there must be a space before your parenthesis, nor you waste time with the linter telling you that you forgot a trailing space somewhere.

If you are familiar with JavaScript rather than Elixir, this is Prettier goal. Handles the syntax for you so you don’t have to bother. If you do Elm, this is elm-format job.

So it really helps productivity.

Elixir formatter is built-in. You can run it with mix format.

The talk focused on how the formatter works to format your code − building an AST, then logically applying the standard rules to re-write your code with proper indentation/spaces…

The meetup was nice and I enjoyed the community. I met and discussed with Henry Olders, who is both a psychiatrist and engineer. We discussed machine learning, Elixir and scalability.

😃👍 I really enjoyed that time and will come back to next sessions. Join us!

To conclude, here are some books recommendation I get from the meetup:

📕 Functional Web Development with Elixir, OTP, and Phoenix
📘 Learn Functional Programming with Elixir (good for beginners and newcomers to Functional Programming)
📄 To spawn or not to spawn to understand how to think in terms of processes, from the author of Elixir in action

À la découverte des Observables

Mon, 19 Mar 2018 00:00:00 GMT

Les Observables sont des flux d’événements paresseux qui peuvent émettre 0 ou N éléments et qui peuvent, ou non, se terminer.

Quickie à Devoxx France (7 avril 2017)

La vidéo

Les slides

À la découverte des observables from Nicolas Carlo

Talk à Human Talks Paris (12 décembre 2017)

La vidéo

Les slides

À la découverte des Observables - HumanTalks Paris 2017 from Nicolas Carlo

Pair-programming makes people share

Mon, 09 Oct 2017 00:00:00 GMT

Pair-programming is two persons, coding on the same screen.

There are different ways to practice pair-programming and mistakes to avoid.

Why do we pair-program? I think the main reason is to communicatebetween developers of the same team.

Communication is a central part of our job: building software. To build a software that satisfies people’s needs, we must talk together to understand these needs. We must share this knowledge among the team to align everyone with a common goal. Thus, communication is key to ensure we are all sailing to the same objective. At the end, everyone’s code is going to be merged into the same codebase. Pair-programming helps us meet before our code does.

There are orher practices with the same benefits: technical retrospectives, code reviews or mob-programming for example. You can combine them.

“But we don’t need pair-programming, we do code reviews.”

Let’s talk about the specificities of pair-programming then.

First, we get real-time feedback during pair-programming. We do have feedback during code reviews too, but it happens later − often when the feature is considered “done”. When we pair with a co-worker, we get instant review of the code we write. Actually, we are thinking together.

Then, as we think together, pair-programming is a better filter against bad ideas or laziness. This can be true for code reviews done correctly − which will hardly happen if the pull-request is big. This is even more true during mob programming.

When we code alone, we put both our best and worst decisions into the codebase.

When we code together, only the best decisions of the team make it through the filter of our combined point of views.

Finally, I think there is something that only happens during pair-programming: people share how they work, tips and tricks, in real-time.

We teach each other our own productivity tips − keyboard shortcuts, techniques… We help each other grow in our day-to-day work. That’s how I learned some features of the tools I use and I didn’t know existed. That’s how I teach my teammates some habits worth trying to waste less time on daunting tasks.

Sharing is why we do pair-programming.

If you do pair-programming, don’t forget to keep it dynamic, switching roles frequently. And do take breaks: pair-programming requires a lot of attention and can be exhausting.

Now tell us, did you have had an “aha” moment doing pair-programming?

Using observables in real life

Thu, 23 Mar 2017 00:00:00 GMT

In this post, I’ll talk about a concrete use case in which Observables turn to be remarkably relevant to make our code cleaner and more maintainable.

How to spot a barcode scanner?!

Yup! This is kind of a specific example. But it perfectly illustrates issues that would beg you for using Observables.

A barcode scanner simply emulates the keyboard. It reproduces the scanned code, emitting keypress signals, ending with the “Enter” key − which key code is 13.

Let’s say we’re developing an app that allows users to search products from their 16-chars code reference. Rather than typing them by hand, users should be able to use a barcode scanner to trigger the search.

“Just let the user focus the search input, scan and you’re done!”

Sure, it’s native behavior.

But the search feature is contained inside a popup that can be open with a button. And we’ve been told the app should be super-ergonomic! Whenever the user scans a barcode, we should open the popup and fill the input with the scanned code.

Now, the problem is: how do we differentiate a scanned code from other keypress events? Let’s say the user hit a key before scanning the code: we don’t want that key to be part of the scanned code!

Solving this, the imperative way

We surely need to listen to keypress events… Then we must… remember the key codes, probably using a buffer! If the key pressed is the “Enter” key, fill the input and clean the buffer. Otherwise, add the key to the buffer!

Let’s try this first shot:

const ENTER_KEY_CODE = 13
let keyCodesBuffer = []

document.addEventListener('keypress', event => {
  const keyCode = event.keyCode

  if (keyCode === ENTER_KEY_CODE) {
    fillInputWithKeyCodesBuffer()
    cleanBuffer()
  } else {
    addToBuffer(keyCode)
  }
})

function fillInputWithKeyCodesBuffer() {
  // …
}

function cleanBuffer() {
  keyCodesBuffer = []
}

function addToBuffer(keyCode) {
  keyCodesBuffer.push(keyCode)
}

Good.

But this is not enough: it doesn’t differentiate scanned codes from regular keypresses!

We know that, if no new keypress is emitted after ~50ms, it’s not a scanned code for sure and we can clean the buffer.

const ENTER_KEY_CODE = 13
const MAX_INTERVAL_BETWEEN_EVENTS_IN_MS = 50
let keyCodesBuffer = []

document.addEventListener('keypress', event => {
  const keyCode = event.keyCode

  if (keyCode === ENTER_KEY_CODE) {
    fillInputWithKeyCodesBuffer()
    cleanBuffer()
  } else {
    addToBuffer(keyCode)
    cleanBufferAfter(MAX_INTERVAL_BETWEEN_EVENTS_IN_MS)
  }
})

function fillInputWithKeyCodesBuffer() {
  // …
}

function cleanBuffer() {
  keyCodesBuffer = []
}

function addToBuffer(keyCode) {
  keyCodesBuffer.push(keyCode)
}

function cleanBufferAfter(timeout) {
  setTimeout(cleanBuffer, timeout)
}

Hmmm… not bad. But there is a subtle bug here: if the code takes more than 50ms to be scanned, it will drop the beginning…

In fact, if a new keypress occurs within 50ms, we should clear the timeout.

const ENTER_KEY_CODE = 13
const MAX_INTERVAL_BETWEEN_EVENTS_IN_MS = 50
let keyCodesBuffer = []
let cleanBufferTimeout

document.addEventListener('keypress', event => {
  const keyCode = event.keyCode

  stopCleanBufferTimeout()
  if (keyCode === ENTER_KEY_CODE) {
    fillInputWithKeyCodesBuffer()
    cleanBuffer()
  } else {
    addToBuffer(keyCode)
    cleanBufferAfter(MAX_INTERVAL_BETWEEN_EVENTS_IN_MS)
  }
})

function fillInputWithKeyCodesBuffer() {
  // …
}

function cleanBuffer() {
  keyCodesBuffer = []
}

function addToBuffer(keyCode) {
  keyCodesBuffer.push(keyCode)
}

function cleanBufferAfter(timeout) {
  cleanBufferTimeout = setTimeout(cleanBuffer, timeout)
}

function stopCleanBufferTimeout() {
  clearTimeout(cleanBufferTimeout)
}

Now we’ve got something working.

Let’s take a step back and think: what if we’ve had the full history of keypress events we could manipulate to filter out scanned codes sequences? Would the code be simpler? Let’s figure this out…

Solving this, with Observables

For this kind of use cases, I find Observables to be a powerful abstraction to represent our data.

Observables are immutable collections of asynchronous events you can manipulate through operators.

If we use things like map and filter over arrays, then we’re already familiar with that way of thinking.

If Observables are still cryptic for you so far, I’d suggest you to read this excellent introduction to Reactive Programming from André Staltz.

So, instead of responding to each event individually, let’s collect all events into a single stream that we can transform.

const keyCode$ = Rx.Observable.fromEvent(document, 'keypress')
  // ---(ev)--(ev)--------(ev)--->
  .pluck('keyCode')
// ---(43)--(51)--------(13)--->

The $ sign at the end of the variable name means “Stream”. It’s a convention I use to know the variable I manipulate is an Observable in non-typed languages, just like I’d call elements an array of element, or $header the jQuery representation of the header.

Now we have a stream of key codes. Any time a keypress event occurs, a new event, which value is the corresponding key code, is emitted.

At the end of the process, we’d like to have a stream we can subscribe to. Each event of the stream should represent the scanned code. So we need to make batches of key codes in a way that isolates scanned codes from parasitic keypresses.

To do so, we can buffer our stream using a debounce strategy: when an event occurs, wait 50ms for another one. If another event is emitted within this time frame, wait another 50ms. If no other event occurs within this time frame, make a batch of the passed events.

This is what we want to achieve with the buffer operator

const MAX_INTERVAL_BETWEEN_EVENTS_IN_MS = 50

const keyCode$ = Rx.Observable.fromEvent(document, 'keypress').pluck('keyCode')

const keyCodesBuffer$ = keyCode$
  // --(43)-(64)----(32)-----(65)-(77)-(13)--->
  .buffer(keyCode$.debounce(MAX_INTERVAL_BETWEEN_EVENTS_IN_MS))
// --([43,64])----([32])-----([65,77,13])--->

So far, so good!

Now, all we have to do is to filter out batches that don’t look like scanned codes. And we know that a scanned code is a sequence that ends with the “Enter” key.

const ENTER_KEY_CODE = 13
const MAX_INTERVAL_BETWEEN_EVENTS_IN_MS = 50

const keyCode$ = Rx.Observable.fromEvent(document, 'keypress').pluck('keyCode')

const keyCodesBuffer$ = keyCode$
  .buffer(keyCode$.debounce(MAX_INTERVAL_BETWEEN_EVENTS_IN_MS))
  .filter(isFromScan)

function isFromScan(keyCodes) {
  return keyCodes.length > 1 && keyCodes[keyCodes.length - 1] === ENTER_KEY_CODE
}

Finally, let’s subscribe to this stream we have created and execute our callback each time a new event is emitted.

Nothing will happen until we subscribe to the Observable, since they are lazy.

const ENTER_KEY_CODE = 13
const MAX_INTERVAL_BETWEEN_EVENTS_IN_MS = 50

const keyCode$ = Rx.Observable.fromEvent(document, 'keypress').pluck('keyCode')

const keyCodesBuffer$ = keyCode$
  .buffer(keyCode$.debounce(MAX_INTERVAL_BETWEEN_EVENTS_IN_MS))
  .filter(isFromScan)

function isFromScan(keyCodes) {
  return keyCodes.length > 1 && keyCodes[keyCodes.length - 1] === ENTER_KEY_CODE
}

function fillInputWith(keyCodes) {
  // …
}

keyCodesBuffer$.subscribe(fillInputWith)

What we did here

This is a visual illustration of what we did to go from keyCode$ − which was created from keypress events − to keyCodesBuffer$ we subscribed to:

Transforming the stream of key codes into a stream of scanned codes

There are a few things to notice with our final code:

we don’t have to manage things like timeout and buffer manually
hence, code is shorter, focused on the actual work
fillInputWith() doesn’t rely on a global buffer, which is more testable and reusable − actually, we are few small steps from making the whole logic purely functional
we just manipulate consts, nothing is reassigned, which is simpler to reason about
created Streams can be reused to do other things ; we can add features without fear of breaking this one
we could easily fix issues in this code, injecting operators into streams creation pipes, if necessary − e.g. we’d probably filter out non-interesting key codes from keyCode$ as simply as .filter(isValidKeyCode)

In my opinion, the one difficult thing is to reason with streams and understand how to solve our use case with given operators.

But, I believe this is something that just takes practice 😉

Des super-pouvoirs à la portée de tou(te)s avec le Feature Flipping

Fri, 13 Jan 2017 00:00:00 GMT

J’ai présenté ce talk le 10 janvier 2017 au meetup HumanTalks Paris chez OCTO Technology.

Le Feature Flipping consiste à activer (ou non) une fonctionnalité en fonction d’une variable, dynamiquement dans le code.

Ça donne le pouvoir de livrer en continu, même quand le code n’est pas terminé ; de faire des tests A/B ; de livrer des fonctionnalités qui ne seront actives qu’un certain temps… Mieux encore : c’est très simple à mettre en place ! Même sur un code legacy.

Néanmoins, « un grand pouvoir implique » de faire gaffe à ce que l’on fait, comme d’habitude. Ce talk était un retour d’expérience sur les do’s & don’ts du Feature Flipping.

Live coding Elm

Mon, 28 Nov 2016 00:00:00 GMT

J’ai présenté ce talk le 9 novembre 2016 au meetup Elm Paris #5 chez Mozilla.

Le code est disponible sur le dépôt du meetup Paris Web Components : https://github.com/pariswebcomps/webapp-exercise/tree/elm

Sur ce dépôt d’ailleurs, il y a une branche par techno (Angular 2, Cycle.js, React, Vue.js…). Si ça vous chante de comparer…

Créer une web app avec Cycle.js

Wed, 12 Oct 2016 00:00:00 GMT

Talk présenté au meetup Paris Web Components #8.

Programme du meetup

Nous allons comparer l’implémentation d’une même webapp par différents frameworks (React, Aurelia, Angular 2, Polymer, Vue.js, Cycle.js).

Chaque speaker aura 20 minutes + 5 minutes de questions pour:

Une présentation du framework
Une présentation des listes et de la réutilisation de composant
Une présentation de la navigation et validation de formulaires
Une présentation de l’écosytème (tooling, build…)

Talk

J’y ai donc présenté l’implémentation avec Cycle.js :

Les slides :

Le code est disponible sur GitHub.

Trello, Kanban & Cycle.js

Tue, 19 Jul 2016 00:00:00 GMT

J’ai présenté ce talk le 29 juin 2016 au meetup Paris.js #57 chez Algolia.

Et voici les slides associés qui contiennent pas mal de liens si vous souhaitez approfondir le sujet :

Le projet est dispo en open-source ici : https://github.com/nicoespeon/trello-kanban-analysis-tool

Quelques retours post-présentation

Pour commencer, il y a bien un exemple de TodoMVC avec Cycle.js : https://github.com/cyclejs/todomvc-cycle/
Concernant le server-side rendering avec Cycle.js : ça se fait bien, toujours avec des streams. Il y a un exemple disponible dans le dépôt de Cycle.jsd’ailleurs.
On m’a posé la question de la différence entre React et Cycle.js (et Elm). Il y a une discussion sur le sujet sur reddit.

Vincent expliquait également il y a quelques mois pourquoi il partait plutôt sur du Cycle.js.

Quant à mon opinion : ça dépend. Partez sur du React/Redux pour des projets qui partent en production parce-que c’est éprouvé et que la communauté est là. Mais si vous avez du temps libre, essayez voir Cycle.js, vous apprendrez des choses =)

Implementing a download button with Cycle.js

Tue, 19 Jul 2016 00:00:00 GMT

The art of merging streams — Photo credits Ian Sane

Programming with Cycle.js / Rx.js needs you to take another approach to the code. We have to switch your brain to think with a different paradigm − functional and reactive, instead of imperative and passive.

Unfortunately, there is a lack of concrete example, from concrete features, from real-life application.

Since I’m building a tool to analyse Kanban metrics from a Trello board with Cycle.js, I do have concrete examples.

Here’s one use case I want to share with you to illustrate how you deal with the user clicking a button to perform an action when everything is a stream.

The feature

Cumulative Flow Diagram (CFD) is a cool metric to help you understand what’s going on with our Kanban flow. In TKAT, data are taken from the Trello API, consolidated then parsed to produce it.

However, this metric is contained in the entrails of the web app. This is not convenient if we want to re-use or share these information in any way (e.g., to build a global report for external stakeholders).

What if the data was parsed and we can download a .csv? That would be awesome.

Building awesomeness, one stream at a time

From a user point of view, we would like to have a “Download” button somewhere close to the graph — probably just below. Clicking on this button will download the .csv of the current graph.

If we change the period/selected lists range and then click on the download button, it should keep matching the displayed graph. We should be able to draw that graph again after we import our data into Excel/GSheet.

In other words: each time a click on the button happens, download in CSV format the latest data.

Let’s interpret this in Cycle.js terms:

“each time …”: subscribe to the following stream
“… a click on the button happens, …”: downloadClicks$, a stream representing button clicks
“… download in CSV format …”: a side-effect, performed by a dedicated ExportToCSV driver
“… the latest data.”: csvData$, a stream representing data

There is already a stream containing CFD data since we display them already. We simply need to map them to produce a csvData$ that matches the input format of ExportToCSV driver.

Then, we need to combine our streams to get the latest value from csvData$whenever — and only when — an item is emitted in downloadClicks$.

Brace yourself, there is a Rx.js operator for that: withLatestFrom().

This is what we want to achieve:

downloadClicks$:  -------x------x----------------x---------->
       csvData$:  ---A---------------B----C--D-------E------>

                     withLatestFrom((clicks, data) => data)

  downloadData$:  -------A------A----------------D---------->

Combining our streams will produce another one (downloadData$) that will emit an item containing CSV-formatted data whenever a click happens on the button.

What about the download?

Downloading a CSV file from formatted data, this looks like a job for a driver!

Indeed, this kind of operations implies side-effects since the program needs to output something that is visible to the user. This is the part where our application unleash its added value. This is also the part where nasty bugs might lie, regarding the environment, the global state of the machine, etc.

That’s why we prefer to move this part into a dedicated driver, away from our application logic.

Our app is pure dataflow while downloading a CSV file is part of side effects stuff.

Note: I didn’t find an open-sourced “downloadToCsv” driver at the time of implementing the feature, so I build my own for this project. With a very little refactoring, it can easily be open-sourced though.

import R from 'ramda'

// Export a driver to be used in our Cycle.js app.
// It takes an `input$` stream that contains `data` to be download.
function exportToCSVDriver(input$) {
  // `data` should be formatted as an Array of Arrays (= lines of CSV).
  // -> `[["name1", "city1", "other info"], ["name2", "city2", "more info"]]`
  input$.subscribe(data => {
    // Parse data to create a CSV file.
    // See: http://stackoverflow.com/questions/14964035/how-to-export-javascript-array-info-to-csv-on-client-side
    let csvContent = 'data:text/csv;charset=utf-8,'
    data.forEach((infoArray, index) => {
      const dataString = infoArray.join(',')
      csvContent += index < data.length ? `${dataString}\n` : dataString
    })

    // Create a link in the page to trigger the download.
    const link = document.createElement('a')
    link.setAttribute('href', encodeURI(csvContent))

    // Name the CSV file based on data attributes.
    // Implementation is based on TKAT specificities (https://github.com/nicoespeon/trello-kanban-analysis-tool).
    // This part can be refactor to open-source the driver.
    const head = R.head(data)
    link.setAttribute('download', `cfd-from-${head[1]}-to-${R.last(head)}.csv`)

    // Required for Firefox.
    document.body.appendChild(link)

    // Download the data file.
    link.click()
  })
}

export { exportToCSVDriver }

The driver subscribe to an observable (= stream) input.

Anytime it emits an event containing formatted data, it will perform the side-effect: download the CSV file from these data. Thus, we would simply pass our downloadData$ stream and we’re done!

And here it is, our “Download .csv” button, waiting for users to click it!

Here is the PR that implemented the feature, in case you want to read the concrete diff.

What are your feelings about this approach? Would you have done it differently? I’d love to discuss about it!

Trello Kanban analysis tool

Mon, 23 May 2016 00:00:00 GMT

nicoespeon.com/trello-kanban-analysis-tool

Drawing a CFD − Photo credits visualpun.ch

Trello ♡ Kanban

Trello is a powerful tool by its simplicity. Being user-centered, it’s easily adopted. It’s flexible enough to adopt a Kanban flow.

Actually, I do use Trello and Kanban a lot for Game Development.

When you do Kanban, there are only a few metrics that you’re interested in. First, you probably want to draw the Cumulative Flow Diagram (CFD). CFD is very easy to build and gives you great overview of what’s happening in the project. What you need to do is to count the number of tasks (cards) of each column (list), each day. Put this on a graph, connect dots, done:

CFD Cheet Sheet from leanguru.pro

It only takes 30 seconds everyday. But, you have to do it everyday. It’s not convenient to reverse engineer it if you missed some days.

Don’t get me wrong: this is not a difficult thing to do and you usually get the team involved in the process, so you are not likely to miss.

But, since you’re using Trello, you might expect to retrieve these information somehow with their API. That would mean not losing time doing this by hand. Also, it would be retroactive!

Among existing tools, Ollert is great at providing Agile metrics from Trello boards, including CFD. Yet, if you’re just interested in Kanban metrics, that might not fit your needs. Plus, it doesn’t give you the second metric you’ll be looking for: Cycle Times over a selected period.

A great use case for a side-project

That unresolved need was a good opportunity for me to get out of my comfort zone and actually practice Functional Reactive Programming (FRP).

Thus, I decided to go with:

ES2015 as this is a brand new JS project started in 2016
Cycle.js, which is based on Rx.js, for the FRP approach
Tape as a test runner — challenging out Eric Elliott advice
Brunch as an automation tool to ease my life with ES2015 stuff
Nvd3 to render graphs — that’s all about data visualization after all
The Trello API
Materialize to quickly set up a decent UI

Making Trello API and Nvd3 work with Cycle.js was quite a challenge. It makes me write my first Cycle.js drivers — which may end up into their own repositories once they will be standard enough to be used independently.

Developing with pure functions, composing them, thinking the application in terms of streams… that was really refreshing. I found that working with Cycle.js/Rx.js made me think differently. The approach is different.

Leaving the app logic free from side effects allows to focus on a fraction of it without messing up something else.

I found this simplifies working on small problems, building components that can be plugged to play together.

Future will tell me if that helps maintainability of a growing application.

I finally got something that does the job

After some time working on it on my spare time, I finally reached the point of an app that does the basic job I needed. This is where I decided to open source what I’ve got so far — if it’s useful to me, it might be for someone else.

Naming things is hard. I went with Trello Kanban Analysis Tool, which I abbreviated TKAT. I’m not really good at naming things… well, at least it stands for what it is and the acronym is easy to catch 😀

So here it is: https://github.com/nicoespeon/trello-kanban-analysis-tool

I just spent some time to polish the README and set up few things to ease contributions.

So, here I am, introducing my ‘‘JS library to analyse Kanban metrics from a Trello board’’.

As a user of it, I already listed stuff I planned to improve, such as:

Make it an web application, served by GitHub
Skin it a bit, following Trello guidelines
Deal with persistence so it would be more convenient for the user
Deal with Trello API in a smarter way (e.g: not flooding the Trello API when a lot of data is missing for a selected period)
Calculating throughput
…

If you are using Trello with Kanban workflow, I’ll be glad you give it a try and give me feedback on what you think / is missing / isn’t working for you.

If you are familiar with Cycle.js or Rx.js, I’m all ears to suggestions. Please go check and criticize my implementation as I certainly not had everything right. Advices on good drivers implementation would be really valuable for example!

If you don’t feel concerned about this but still read the whole post… well that’s cool ¯\_(ツ)_/¯

Thanks, take care and have fun!

At least, it does the trick.

Point-free JavaScript avec R.converge / _.over

Tue, 12 Apr 2016 00:00:00 GMT

Faire converger les fonctions pour aller vers la simplicité.

Le contexte

Je travaille sur un side-project qui est surtout un prétexte pour moi de pratiquer une approche plus fonctionnelle de JavaScript. En l’occurrence, ici je m’amuse surtout avec ES6, Cycle.js et Ramda.

Ainsi, j’en profite pour pratiquer la programmation de style point-free, aka tacit programming, lorsque c’est pertinent.

Pour résumer l’idée : cela veut dire que qu’il n’est pas nécessaire d’expliciter nos données. Lorsqu’elle est utilisée avec sagesse, cette technique permet de conserver un code clair et concis en supprimant les inutiles déclarations de variables intermédiaires. Voyez plutôt :

// From https://github.com/MostlyAdequate/mostly-adequate-guide/blob/master/ch5.md#pointfree

// Not point-free because we mention the data: name
let initials = name =>
  name
    .split(' ')
    .map(compose(toUpperCase, head))
    .join('. ')

// Point-free style
let initials = compose(join('. '), map(compose(toUpperCase, head)), split(' '))

initials('hunter stockton thompson')
// 'H. S. T'

Mais je me suis retrouvé dans une situation qui pourra vous sembler familière si vous vous essayez, comme moi, à ce style de programmation.

Le problème

J’ai une fonction daysSpent qui prend une Date, une autre Date et qui me retourne le Number de jours qui se sont écoulés entre elles.

daysSpent : Date -> Date -> Number

Puis, j’ai une list d’éléments où chacun dispose d’un attribut date :

[
  { "list": "Backlog", "date": "2016-04-01" },
  { "list": "Card Preparation [2]", "date": "2016-04-01" },
  { "list": "Production [3]", "date": "2016-04-02" },
  { "list": "Tests QA [2]", "date": "2016-04-05" },
  { "list": "Mise en live [1]", "date": "2016-04-05" },
  { "list": "In Production", "date": "2016-04-06" },
  { "list": "Live (April 2016)", "date": "2016-04-08" }
]

Ce que je souhaite consiste à calculer le nombre de jours passés entre le premier et le dernier élément de ma liste (ce qui s’appelle le Lead Time dans mon contexte).

Bon et bien j’y suis presque. J’ai certainement besoin de me servir de ma fonction daysSpent. Le soucis c’est que le format n’est pas tout à fait adapté. En utilisant Ramda, je suppose qu’une approche naive au problème ressemblerait à ceci :

import { pipe, prop, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = items =>
  daysSpent(pipe(head, prop('date'))(items), pipe(last, prop('date'))(items))

Ça fonctionne c’est sûr… mais quelque chose ne sonne pas très juste ici.

Je suis forcé de déclarer items et de le balader partout parce-que j’ai besoin de le transformer de différentes manières avant de pouvoir le traiter. Je ne peux pas faire s’écouler naturellement items le long d’une composition de fonctions car je dois le faire diverger afin de respecter l’arité dedaysSpent.

C’était une problématique assez récurrente… que Ramda résout !

R.converge à la rescousse

Voilà le topo :

// What I ended up with
const getX = input => getY(parseA(input), parseB(input))

// What I was trying to achieve, some sort of:
const getX = anyFunction(getY(parseA, parseB))

Parmi la trousse à outils de Ramda, il y a une fonction qui fait exactement ça : R.converge. La syntaxe est la suivante :

const getX = R.converge(getY, [parseA, parseB])

Tadaaaaam :

import { converge, pipe, prop, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = converge(daysSpent, [
  pipe(head, prop('date')),
  pipe(last, prop('date')),
])

Ceci va appeler daysSpent avec les arguments attendus à partir de l’input. Plus besoin de déclarer ce dernier avec une variable, je peux me concentrer sur les opérations.

D’ailleurs, le refactor est encore plus simple:

import { pipe, pluck, converge, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = pipe(
  pluck('date'), // first convert input into [Date]
  converge(daysSpent, [head, last]) // then pick proper ones for calculation
)

leadTime pluck les dates de input, puisconverge le head et last de la liste dansdaysSpent pour déterminer le résultat. Je trouve qu’il y a de la beauté dans une telle simplicité.

Oh et si vous êtes plutôt du genre lodash (ce qui est mon cas, mais j’ai toujours voulu voir ce que Ramda avait dans le ventre), lodash-fp fait également du bon boulot. John-David Dalton suggère une approche différente :

import { pipe, pluck, over, head, last, spread } from 'lodash/fp'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = pipe(
  pluck('date'), // first convert input into [Date]
  over([head, last]), // then turns them to our arguments array [ FirstDate, LastDate ]
  spread(daysSpent) // finally spread arguments to the function
)

Si vous souhaitez explorer le sujet en profondeur :

Un article sur le point-free JavaScript
Get started avec Cycle.js
The philosophy of Ramda − même si lodash-fp fait du bon travail en pratique aujourd’hui, Ramda se combine parfaitement avec les concepts de programmation fonctionnelle

Point-free JavaScript with R.converge / _.over

Tue, 12 Apr 2016 00:00:00 GMT

Get to simplicity, converging functions.

The context

I’m working on a side-project which is mainly a playground for me to practice a more functional approach to JavaScript. There I’m mostly playing with ES6, Cycle.js and Ramda.

Along this journey, I’m doing my best to practice point-free style programming, aka tacit programming, when relevant.

To put it in a nutshell: it means that you never have to say your data. When used wisely, it can help keeping your code clear and concise, avoiding unnecessary intermediate variable declarations. See for yourself:

// From https://github.com/MostlyAdequate/mostly-adequate-guide/blob/master/ch5.md#pointfree

// Not point-free because we mention the data: name
let initials = name =>
  name
    .split(' ')
    .map(compose(toUpperCase, head))
    .join('. ')

// Point-free style
let initials = compose(join('. '), map(compose(toUpperCase, head)), split(' '))

initials('hunter stockton thompson')
// 'H. S. T'

Then, I found myself stuck in a situation that may sound familiar if you ever tried to achieve that.

The problem

I’ve got a daysSpent function that takes a Date, another Date and then return the Number of days spent between those.

daysSpent : Date -> Date -> Number

Then, I have a list of items, each of which having a date attribute:

[
  { "list": "Backlog", "date": "2016-04-01" },
  { "list": "Card Preparation [2]", "date": "2016-04-01" },
  { "list": "Production [3]", "date": "2016-04-02" },
  { "list": "Tests QA [2]", "date": "2016-04-05" },
  { "list": "Mise en live [1]", "date": "2016-04-05" },
  { "list": "In Production", "date": "2016-04-06" },
  { "list": "Live (April 2016)", "date": "2016-04-08" }
]

What I want is to calculate the number of days spent between the first item of the list and the last one − which is something that will be called Lead Time in my context.

Well, I’m almost there. What I need is probably to use the daysSpent function. However, the format doesn’t quite match. I guess the naive attempt to do so, using Ramda, would look like:

import { pipe, prop, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = items =>
  daysSpent(pipe(head, prop('date'))(items), pipe(last, prop('date'))(items))

It sures work, but… something feel weird here.

I’m doomed to declare items and spread it around because I need to parse it into different ways before I can process it. I can’t make items flow nicely since I need to branch it to respect the arity of daysSpent.

This used to be a common issue… which Ramda solves!

R.converge to the rescue

Here is the thing:

// What I ended up with
const getX = input => getY(parseA(input), parseB(input))

// What I was trying to achieve, some sort of:
const getX = anyFunction(getY(parseA, parseB))

Among Ramda toolset, there is a function for that: R.converge. Syntax is the following:

const getX = R.converge(getY, [parseA, parseB])

Aaaand, there we go:

import { converge, pipe, prop, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = converge(daysSpent, [
  pipe(head, prop('date')),
  pipe(last, prop('date')),
])

This will call daysSpent with properly expected arguments from input. Needless to declare it with a variable, I focus on operations.

Hence, refactoring got event easier:

import { pipe, pluck, converge, head, last } from 'ramda'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = pipe(
  pluck('date'), // first convert input into [Date]
  converge(daysSpent, [head, last]) // then pick proper ones for calculation
)

leadTime pluck input dates, then converge the head and last of the list into daysSpent to get the result. I found some beauty in such simplicity.

Oh and if you’re much a lodash person − I am, but I always wanted to experiment what Ramda got − lodash-fp is doing a pretty good job too. John-David Dalton suggested another approach to do so:

import { pipe, pluck, over, head, last, spread } from 'lodash/fp'
import { daysSpent } from './utils/dates'

// leadTime : [{date: Date}] -> Number
const leadTime = pipe(
  pluck('date'), // first convert input into [Date]
  over([head, last]), // then turns them to our arguments array [ FirstDate, LastDate ]
  spread(daysSpent) // finally spread arguments to the function
)

If you’d like to explore further:

An article about point-free JavaScript
Get started with Cycle.js
The philosophy of Ramda − even though lodash-fp is doing a great practical job today, Ramda plays nicely with FP concepts

Gérer ses mails avec la méthode « Inbox Zero »

Thu, 18 Feb 2016 00:00:00 GMT

Le principe

L’idée ici est de vous présenter en quoi consiste cette méthode de productivité, comment ça se met en place et ce qui fonctionne pour moi.

Le constat de base est le suivant : les mails qui s’entassent peuvent nous peser sur la conscience.

Au mieux, on essaie de ne pas trop accumuler de messages non-lus, on s’efforce de se souvenir constamment quels sont les mails urgents, ceux qui attendent une réponse, ceux qui sont juste du spam… Au pire, on laisse s’entasser le 2342e mail non-lu, on oublie de traiter certains e-mails plus ou moins importants, on n’est pas vraiment « joignable » par mail.

Le concept de l’inbox zero consiste donc à nettoyer notre boite mail pour éviter qu’elle se transforme en TODO-list non contrôlée.

Cela nous permet de garder l’esprit serein devant notre boite vide, car on sait que l’on oublie rien. C’est d’ailleurs le moyen le plus efficace que j’ai pu adopter pour FAIRE les choses jusqu’à aujourd’hui.

Une journée sereine, même GMail est heureux !

Concrètement, comment ça se met en place ?

C’est la partie la plus difficile. Honnêtement.

Il faut voir cela comme un grand ménage de printemps, la technologie en plus !

Un client mail pour les gouverner tous

La première chose à faire, selon moi, c’est de pouvoir gérer l’ensemble de nos boites mails au même endroit. Tout est plus simple lorsque la réception et l’envoi des e-mails se font depuis un seul endroit.

Pour cela, il suffit de configurer et d’utiliser un client mail (il en existe un paquet). Il est aussi possible de configurer GMail pour cela, par exemple. L’embarras est surtout dans le choix.

Il peut être intéressant de créer des labels (ou équivalents) pour distinguer les e-mails entrants en fonction de la boite d’origine.

Archiver est un jeu d’enfant

C’est l’astuce au cœur de la philosophie « Inbox Zero » : archivez !

Commencez votre ménage en archivant l’ensemble des mails de votre boite de réception.

Un client mail qui se respecte vous proposera un bouton pour archiver vos e-mails en toute simplicité. De plus, il doit être aisé de retrouver un message archivé grâce au moteur de recherche. C’est la raison pour laquelle il vaut mieux tout archiver sans trop se poser de question pour commencer.

D’aucuns créent des dossiers pour ranger les mails en fonction de leur nature. En ce qui me concerne, j’ai cessé de le faire, car c’est une perte de temps qui ne s’est jamais révélée utile.

La philosophie qu’il faut adopter est la suivante : la boite de réception sert aux mails non-lus, non-traités, qui attendent une réponse ou une action à planifier. Si un mail a été répondu / traité / n’attend aucune réponse, on l’archive. Si c’est un mail important que l’on souhaite retrouver rapidement plus tard, on peut éventuellement lui ajouter un label si cela nous facilite la vie.

Le concept est donc assez simple, mais efficace. Il ne nécessite rien d’autre que la possibilité d’archiver, un moteur de recherche efficace et de la rigueur au quotidien.

Au quotidien

Au quotidien l’objectif est clair : 0 mail dans la boite de réception.

Avant toute chose, il va sans dire que dédier deux ou trois créneaux dans la journée pour traiter ses e-mails est bien plus efficace que de garder sa boite mail ouverte et de les traiter en continu. Il est rare que cela ne puisse pas atteindre, et il est contre-productif de se laisser déranger par chaque mail qui arrive.

Ensuite, tout est dans l’action. Il faut décider. Vite.

Il faut éviter de laisser trainer les mails et les décisions. Pour cela, il y a plusieurs scénarios.

L’e-mail qui donne des choses à faire

Partons du principe que nous organisons les choses que nous avons à faire dans un système externe, quel qu’il soit : une TODO-list papier, des post-its, un logiciel de gestion de tâches… Personnellement, j’utilise la technique Kanban avec Trello, mais c’est une autre histoire.

Suite à cet e-mail donc, nous avons quelque chose à faire :

qui n’est pas absolument indispensable : on oublie. On peut éventuellement le noter dans le coin des « choses à faire quand j’ai du temps libre ».
que quelqu’un d’autre peut faire : on délègue si possible (c’est bête à dire, mais il ne faut pas l’oublier).
qui peut se faire en 2 minutes : Just. Do. It. Now.
qui doit être fait à un moment précis : on se planifie un rappel (Calendrier, SMS planifié…).
qui doit être fait plus tard : on ajoute un TODO dans notre système. C’est planifié, ce ne sera pas oublié ! Il existe une extension Chrome GMail to Trello pour ceux que ça intéresse.

Une fois que c’est décidé, on archive !

L’e-mail auquel il faut répondre

Si répondre à ce mail prend 2 minutes, on le fait tout de suite et on archive !

Si la réponse demande un peu plus de temps, on laisse l’e-mail de côté dans la boite de réception et on se prévoit un TODO pour répondre à cet e-mail en particulier. On peut ainsi prioriser cette tâche parmi les autres et on ne se stresse plus de ne pas avoir encore répondu à ce mail : c’est prévu !

Ah et une fois que la réponse est envoyée… On archive !

L’e-mail qui n’attend pas de réponse de notre part

On le lit, on prend note, on l’archive. Et hop !

L’e-mail indésirable

Généralement, la newsletter, la publicité inutile, le mail qui vient juste polluer notre boite (et notre attention).

Avant de l’archiver / supprimer, nous allons prendre 1 minute pour ouvrir ce mail, chercher le lien « se désinscrire » (théoriquement situé en bas du mail) et cliquer dessus.

Ces quelques secondes investies systématiquement vont réduire considérablement le nombre de mails indésirables à l’avenir. C’est un bon investissement !

Bilan personnel

Cela fait un peu plus d’un an maintenant que j’ai adopté cette manière d’aborder ma boite mail.

Le plus gros changement, bénéfique, c’est d’être capable de se décider vite. Ne pas laisser s’entasser les e-mails dans une boite de réception qui devient un énième TODO-list. Ne pas perdre son temps à essayer d’organiser, de classer les e-mails plutôt que de les traiter.

Je suis particulièrement réceptif à cette approche continue, au fur et à mesure, qui s’adapte parfaitement à une méthodologie Kanban. Ma boite mail est devenu fiable, sans être une source de stress. C’est plus simple, plus efficace.

Il y a un paquet d’articles sur la question si vous avez besoin d’aller plus loin. En voici quelques-uns :

Parvenir au “inbox zéro”, qui reprend ce dont je viens de parler ici avec quelques exemples concrets
Le guide en 2 étapes pour ne plus se laisser dominer par sa boite mail, un autre article sur le même sujet pour multiplier les points de vue
Comment j’ai atteint l’inbox zero (et comment vous allez y arriver), qui se focalise concrètement sur le quotidien
TODO Zero, qui propose une alternative qui consiste à se servir de sa boite mail comme TODO-list

Manage your e-mails with the "Inbox Zero" method

Thu, 18 Feb 2016 00:00:00 GMT

The main idea

My goal here is to present what is that productivity method about, how do we set up and what does work for me.

The base picture is the following: emails that accumulate make us feel guilty.

At best, we struggle not to accumulate too much unread messages, we force to constantly remember which are the urgent ones, those which need a reply, those that are just spam… At worst, we just let the 2342th unread email arrive, we forgot to handle some that might be important, people can’t really “join us” with an email.

Inbox zero is a concept that consists in cleaning up our mailbox to avoid it turns into a uncontrolled TODO-list.

It helps keeping a serene spirit in front of our empty inbox, because we know that nothing has been forgotten. This is surely the most efficient technique I’ve adopted to get things DONE until today.

You don't have anymore email. Have a nice day!

How to set up, concretely?

This is the most difficult part. I honestly think it.

Just let’s deal with it like it’s a big numerical spring clean up!

An email client to rule them all

According to me, the very first thing to do is to be able to manage all of our mailboxes at a single place. Everything becomes simpler when both receiving and sending emails can be done from a single place.

We just need to configure and use one of the numerous email clients that exist. You can even configure GMail to do that. The problem is choice.

That could be handful to create labels − or equivalents − to distinguish incoming emails regarding their original mailbox.

Archive is easy as pie

This is the core of “Inbox Zero” philosophy: just archive!

Start your cleaning up by archiving all emails from your mailbox.

A decent email client will give you the possibility to archive at the push of a button. Furthermore, it should be easy to search for an archived message thanks to the search bar. This is why we should first just archive all the thing and move on.

Some people would create folders to classify emails regarding their nature. I did stop doing this since it’s a waste of time that has never proved useful for me.

The philosophy we need to have is the following: the inbox is here to handle incoming emails that are still unread, not handled, waiting for a reply or some task to plan. If an email is read / replied / handled / don’t need any reply anymore, archive it. If that’s an important one and we want to quickly retrieve it later, we can eventually add a label if that ease our life.

The concept is simple, yet efficient. It doesn’t rely on anything but the capacity of archiving, an efficient search engine and rigour in everyday life.

In everyday life

The day-to-day objective is clear: 0 email in the inbox.

To dedicate 2 or 3 slots in our day to deal with emails is far more efficient than keeping our mailbox open and treat incoming messages all day long. It usually can wait and it’s counterproductive to let every new incoming email disturb us in what we’re doing.

Then, this is just action. We should decide. Quick.

We should not procrastinate emails and decisions. There are a couple of scenarios for that.

The email that requires us to do something

Let’s assume we organize thing we have to do with an external system, whatever it is: a paper TODO-list, post-its, a task manager software… I personally use the Kanban technique with Trello, but that’s another story.

Then, this email requires us to do something:

which is not absolutely necessary : forget it. We can eventually drop it to the “things to do on spare time” list.
that someone else can do : delegate when possible − that’s sound dumb to say but still don’t forget you can delegate.
that can be done in less than 2 minutes : Just. Do. It. Now.
that should be done at a very specific moment : let’s plan a reminder (Calendar, planned SMS…)
that should be done later : let’s add a TODO to our system. Here it is, planned and won’t be forgotten! For Chrome users, there is even a GMail to Trello extension.

Once decision is made, archive it!

The email we should reply to

If that reply takes less than 2 minutes, let’s do it now and archive this email!

If it will take more time, we’ll better leave the email into the inbox and plan a TODO to reply to this specific email. Thus, we can prioritize this task with all the other things we have to do. Still we don’t stress for not having replied to this email yet: it’s all planned!

And when reply has been sent, guess what… we archive this email!

The email that doesn’t need a reply from us

We read, we take note, we archive. Voila!

The undesirable email

This is usually the newsletter, the useless ad, that email which is just polluting our inbox − and our attention.

But before we do archive / delete this one, we’ll take an extra minute to open it, search for the unsubscribe link that is probably at the bottom of the email and click on it.

The few seconds we systematically invest in doing this will considerably reduce the number of undesirable emails we’ll receive later. This is a good investment!

Personal feedbacks

It has now been a little over a year since I start using this technique to manage my mailbox.

The biggest valuable change is to be able to decide quickly. Don’t let emails stack into an inbox that is just becoming a crowded TODO-list in itself. Don’t lose time trying to organize and classify emails instead of just treating them.

I’m particularly receptive to this continuous approach. Doing thing little by little just fits perfectly with the Kanban methodology. My mailbox is now reliable without being a source of stress. It’s simpler and more efficient.

There are a bunch of posts around there if you want to go deeper. Here are few of them:

A definition of Inbox Zero with Merlin Mann introducing the inbox zero approach in a Google Tech Talk
5 Tricks to Finally Achieve Inbox Zero, which advise some concrete tools and links
How I Achieved Inbox Zero in 4 Steps, which tells the same story with another point of view
ActiveInbox FAQ, which is a service over GMail to help you achieve inbox zero and which provide a very nice FAQ with a cool flowchart to visualise the decision process
TODO Zero, which is proposing an alternate solution that consists in making your mailbox be your TODO-list system

Kanban et Game Development avec Trello

Tue, 26 Jan 2016 00:00:00 GMT

Vidéo & Slides

J’ai présenté ce talk le 2 février 2016 au meetup Trello French UG #02.

L’article détaille le sujet en profondeur ci-dessous.

Contexte

Metidia, une start-up qui développe des jeux vidéo

Je suis associé d’une start-up parisienne qui s’appelle Metidia.

Concrètement, nous développons des jeux vidéo autour de produits de consommation car nous voulons changer l’univers de l’achat en ligne. Ainsi, nous travaillons sur Vinoga : un jeu Facebook de social-farming (pensez « FarmVille », « Hay Day ») sur le thème du vin. Vous êtes vigneron(e) qui redécouvrez les étapes de production de véritables bouteilles au travers de votre aventure. Entre deux vendanges, vous pouvez donc jeter un œil à votre carte des vins, personnaliser, commander puis déguster en vrai les crus que vous avez virtuellement produits.

Le challenge d’une start-up est d’itérer d’une idée de départ à un business model qui fonctionne avant d’être à cours de ressources.

Et, entre les multiples casquettes typiques d’une start-up, j’ai celle du responsable de la partie production : faire en sorte que l’équipe concrétise les idées, teste les hypothèses et crée un jeu qui corresponde aux attentes des clients-joueurs.

Notre équipe de production est composée de 1 Game Designer, 1 Graphiste et 2/3 Développeurs. Si nous avions commencé à 2 avec une organisation de type La Rache, il a vite fallu nous adapter pour ne pas répéter les déboires des premiers temps (assets produites, mais devenues obsolètes avant d’être intégrées ; faible qualité du code qui doit être retravaillé à cause des bugs…).

Nous avons profité de notre flexibilité pour adopter de facto les pratiques Agiles. J’ai pas mal tâtonné à ce sujet. Par exemple, nous avons beaucoup appris de Scrum pour nous organiser, mais il s’est avéré trop lourd, inadapté pour notre contexte.

En fin de compte, je pense que l’Agile est un buffet dans lequel il faut se servir.

Au fur et à mesure, nous avons composé un processus qui nous est adapté, en picorant les bonnes pratiques qui fonctionnent pour nous.

Finalement, Kanban s’est révélé être particulièrement efficace pour l’équipe : suffisamment flexible pour s’adapter au quotidien ; mais assez solide pour éviter que ça se disperse dans tous les sens (ce qui n’est pas toujours évident avec des esprits créatifs).

Kanban, kézako ?

Pour résumer simplement, Kanban est « un système visuel de gestion des processus qui indique, quoi produire, quand le produire et en quelle quantité ».

Le cœur de Kanban consiste à visualiser le processus de production pour mettre en place un système de tirage limité des tâches en cours. Ce qui veut dire qu’on limite le nombre de tâches en parallèle pour chaque étape du processus. Lorsqu’une place est libre, c’est l’étape en aval qui vient prendre une tâche en amont (système de tirage) et non l’inverse.

Concrètement, voici à quoi ressemble un processus Kanban en action : One day in Kanban land

Le passage à Kanban est assez simple car l’on part de l’existant :

identification des processus existants (ex : processus de production, de support au joueur…)
décomposition des workflows pour chaque processus
fixation des limites de tâches en cours (là encore, on commence à partir de l’existant)

Puis, l’idée est de venir améliorer le flow au fur et à mesure en impliquant l’équipe. C’est le Kaizen, composante essentielle de Kanban : l’équipe fait un point régulièrement pour améliorer de manière incrémentale et continue son organisation. Cela permet à l’équipe d’adapter son fonctionnement à son contexte, de tester des choses, de s’adapter au changement…

C’est ainsi que nous avons fait évolué au fur et à mesure les limites de tâches en cours (= WIP) de chaque étape du processus jusqu’à atteindre des valeurs qui nous permettent d’être plus productifs (WIP bas = débit plus important), sans nous retrouver bloqués… ce qui est bon pour le moral !

Big picture

Nous avons intégré Trello depuis le tout début, dès 2013. Gratuit, intuitif, simple à prendre en main, c’est notre tableau blanc virtuel et compagnon dans l’aventure qui a pu évoluer avec nous à mesure que nous nous organisions.

Les boards (= tableaux) de Trello sont très flexibles, ce qui nous permet de les faire évoluer avec le temps au gré des besoins.

Nous avons donc diverses boards qui se créent ou se ferment en fonction des projets. L’organisation de ces boards s’adapte au contexte : un projet temporaire planifié en mode GANTT pour des besoins business (avec l’extension Elegantt) ; un simple Kanban TODO > Doing > Done pour gérer un sous-projet temporaire ; etc.

À côté de ça, nous avons une board pour chaque processus identifié, à savoir :

Production
Business
Support
Communication

Chaque board représente une activité qui a son workflow.

Dans cet article, je vais me concentrer exclusivement sur le fonctionnement de la board de production.

La board de production

La board (Kanban) de production représente notre force de production, le travail de l’équipe de production. Et ce, peu importe ce qu’il faut produire : correctif de bug, nouvelle feature sur Vinoga ou sur un autre produit, hotfix… Tout ce qui est livré.

Cela permet d’être honnête sur la capacité de travail de l’équipe, de prioriser tout ce que nous faisons et d’homogénéiser le processus de production.

Notre board de production

Goals

La première liste de la board contient nos key metrics : les 3/4 KPIs les plus importants pour nous. Ça permet à l’équipe de toujours les avoir sous les yeux et c’est motivant.

Les objectifs sont revus chaque mois, ce qui nous permet de faire le point sur notre cap et nos performances.

C’est aussi l’occasion de célébrer les réussites tous ensemble, parce que c’est bon pour le moral !

Templates

Cette liste est plutôt utilitaire : elle contient les cartes qui font office de template pour nous simplifier la vie.

En fait, il n’y a pas vraiment de « template de carte », car créer une carte quand on a une idée doit rester quelque chose de simple. Tout le monde peut créer une carte, mais tout le monde ne pense pas à dupliquer une carte pour cela : cela n’a rien d’intuitif.

En revanche, cela nous est très utile pour les templates de checklists.

En effet, Kanban préconise de « rendre les normes de processus explicites » : chacun doit pouvoir savoir si une carte est prête pour passer à la prochaine étape du flow ou non. Pour cela, l’équipe se met d’accord sur (et fais évoluer) les règles de sortie de chaque étape du flow de production. Et, après avoir tâtonné sur le meilleur format pour ce faire avec Trello, les checklists se sont avérées être le moyen le plus efficace !

Exemple de template pour les conditions de sortie explicites

Ainsi, lorsque l’on en a fini avec une carte, chacun sait qu’il faut créer la checklist de sortie. Ce qui est aisé avec les templates :

Il suffit de copier un template de checklist

Notre astuce pour retrouver rapidement nos checklists templates, c’est de nommer la carte de manière à ce qu’elle apparaisse en premier dans la liste déroulante.

D’où le préfixe (Template) qui fait très bien l’affaire.

Icebox / Backlog

Le fonctionnement du « Backlog » est probablement ce qui nous a causé le plus de tâtonnement : où mettre les idées, les TODOs à venir, sans que ce soit lourd ou long à traiter.

Nous avons donc testé pas mal de choses, y compris une board « Planning » à la manière de UserVoice. Mais ce qui a marché pour nous fut d’intégrer une liste « Backlog » directement dans la board.

Les cartes y sont priorisées, ce qui veut dire que l’équipe traitera, dès que possible, la carte qui est tout en haut. Ainsi, nous pouvons re-prioriser les cartes jusqu’au dernier moment.

Décider le plus tard possible pour être plus efficaces.

Pendant un temps, nous limitions la taille du backlog pour éviter que les cartes ne s’y accumulent plus vite qu’elles ne puissent être traitées. Cette limitation a finalement été abandonnée, car l’équipe est désormais capable de s’auto-gérer. Le Cumulative Flow Diagram nous permet de visualiser rapidement la tendance et de savoir si nous ajoutons plus de cartes que raisonnable, ou non.

« Backlog » contient donc les cartes que nous avons décidé de traiter prochainement, généralement parce-qu’elles impactent l’un des goals que nous nous sommes fixés.

Cela étant, vous n’empêcherez pas une équipe créative d’avoir des idées ! Et pour favoriser cela, il faut faire tomber les barrières. C’est le rôle de la liste « Icebox ».

Sans limite de cartes, elle permet de recueillir toutes les idées ou suggestions qui ne vont pas forcément faire partie du backlog (ex : des idées pour améliorer la monétisation du jeu tandis que le focus actuel est porté sur la rétention).

Nous repassons régulièrement sur les cartes de cette liste pour les déplacer dans le backlog si elles deviennent pertinentes, les supprimer si elles ne sont plus valables ou pour y ajouter des idées, des compléments d’information…

Le fait de garder cette liste dans la board simplifie les choses. Cela rend le tout plus flexible, tout en nous permettant d’avoir une vision à moyen-long terme. Mais on ne perd pas trop notre temps dessus, car, en start-up, le moyen-long terme ça peut changer très vite.

Workflow de production

Le flux de production

Ceci représente concrètement les différentes étapes par lesquelles chaque carte va passer.

Chaque étape a une limitation du travail en cours (le WIP) indiquée dans le titre de la liste.

Les cartes s’écoulent en mode par tirage (mode « pull ») : lorsque le traitement d’une carte est terminé pour une étape, elle reste à ce niveau (avec un petit label vert) jusqu’à ce que quelqu’un de l’étape d’après soit disponible pour s’en occuper. Tout cela, dans le respect des limites de WIP.

Exceptionnellement, il peut y avoir des cartes qui font fi des limites de WIP. Ça peut être le cas d’une urgence (ex : hotfix critique en production) ou d’une attente externe à une carte (ex : en attente de validation de Facebook). Dans ces cas-là, les cartes ont un label rouge explicite. Et ces cas-là sont rares.

Card Preparation

Les cartes y sont préparées pour la suite du flow.

C’est à partir de ce moment que l’on va décrire le use case de la carte, ainsi que l’objectif SMART de celle-ci. Toute carte a un objectif (sinon, que ferait-elle ici ?). Que ce soit de corriger un bug en production ou d’implémenter une nouvelle fonctionnalité, il y a une raison pour laquelle nous allons traiter cette carte plutôt qu’une autre. Et, surtout, nous allons déterminer comment nous saurons si l’objectif est atteint et que faire en cas de succès ou d’échec.

Ainsi, nous ne perdons pas de temps à trop préparer l’ensemble des cartes qui sont dans le backlog. Seul l’objectif général importe, mais c’est dans Card Preparation que l’on va creuser l’idée, se mettre d’accord sur la portée de la carte et, éventuellement, de son découpage en plus petites cartes (notamment dans le cadre d’une mécanique de jeu, qui se décompose souvent en petites fonctionnalités que l’on peut intégrer au fur et à mesure).

Production

C’est ici que va se faire le game design / spelling / graphisme / développement d’une carte.

Chacun est libre de se servir de checklists, voire même d’ouvrir une board temporaire, pour s’organiser.

Pendant un temps, chaque étape de production (specs, graphisme, dév…) était représenté par une liste. Néamoins, ce n’était pas assez flexible et ne reflétait pas la réalité.

Une seule liste permet plus de latitude afin par exemple que les développeurs travaillent directement avec les graphistes lors de l’intégration ; ou lorsqu’il n’y a pas de graphiste disponible pendant 1 semaine (on évite les « bulles d’air » dans le flow).

Tests QA

C’est ici que nous allons nous assurer que le rendu est conforme à ce qui était attendu. C’est habituellement un pair qui s’occupe de cette partie pour assurer la qualité (le game designer, quelqu’un du business, un autre développeur que celui qui a codé…).

On s’assure également ici que nous sommes en mesure d’analyser l’objectif SMART défini pour cette carte.

Si un souci est relevé, la carte reste ici et bloque le flow tant qu’il n’est pas corrigé. Ainsi, l’équipe se préoccupe de terminer les tâches en cours avant d’en attaquer de nouvelles. Et chacun se préoccupe de la qualité de ce qui est produit.

Mise en live

Il s’agit de la procédure de livraison en production de ce qui a été produit.

Tout est déployé en continu. Au besoin, nous faisons du feature flipping pour activer / désactiver des fonctionnalités.

Live

Une fois en production, les cartes ne sont pas oubliées.

En effet, à chaque carte a été associé un objectif SMART, validé par l’équipe. Une fois en production, nous analysons ce dernier.

Cela peut être fait une fois la carte en production (dans le cas des correctifs par exemple), ou bien plus tard si l’analyse doit collecter des données auparavant (c’est par exemple le cas des tests A/B). Dans cette situation, une date d’analyse est planifiée sur la carte et une personne assignée.

Une fois l’analyse faite, la carte est considérée comme terminée. Elle est déplacée dans le Live du mois en cours. Nous appliquons également le scénario prévu en cas de succès ou d’échec de l’objectif, qui était finalement notre hypothèse au sens du Lean Startup.

Ainsi, que ce soit un succès ou un échec, nous avons appris quelque chose une fois qu’une carte passe en Live. Nous avons validé ou invalidé une hypothèse, ce qui nous éclaire sur la suite.

Nous faisons un bilan mensuel sur les cartes mises en live = ce que nous avons appris.

Lessons learned & Anecdotes

En vrac, voici quelques trucs que nous avons appris ou mis en place et qui nous servent beaucoup.

Rester simple

Je ne vais pas rabâcher le principe KISS, mais c’est vraiment essentiel à garder en tête.

Dans notre cas par exemple, je me suis rendu compte que plus je créais de boards pour séparer le travail avec des workflows particuliers à chaque board (à la manière de UserVoice par exemple), moins c’était efficace. Il faut que l’essentiel soit à portée de main, sous les yeux, pour rester focus.

Sinon ? Ce ne sera pas adopté, pas utilisé dans la pratique par l’équipe… parce que ce n’est pas pratique pour l’équipe.

Concernant les estimations des cartes…

… pour nous c’est une perte de temps.

Il y a moult débats sur la question et je n’entrerai pas ici dans le détail.

Mais en ce qui nous concerne, Kanban nous a permis d’arriver aujourd’hui avec une « ligne de production » efficace et rapide. Avec nos indicateurs, nous sommes capables de connaître notre vitesse moyenne de production. En homogénéisant au mieux la taille des cartes qui arrivent, et en nous concentrant sur l’essentiel, nous intégrons en continu les changements dans le jeu.

Si une carte est urgente, il suffit de la placer en haut du backlog et elle sera naturellement intégrée en production dans un délai approximativement connu, fiable et raisonnable (8 jours calendaires actuellement, en moyenne).

Si cela est plus urgent encore et que cela ne peut pas attendre, alors un label rouge fera passer cette carte en priorité avant le reste (c’est la fast-line). Mais ce genre d’urgence est rare une fois que l’on a une équipe de production capable d’intégrer au mieux, le plus vite possible.

Management visuel

« Visualiser » est l’un des piliers centraux de Kanban en particulier et d’une manière générale au sein des pratiques Agiles.

Trello s’intègre parfaitement pour cela avec des power-ups tels que GitHub, ou avec son API.

En ce qui nous concerne par exemple, nous changeons la couleur du background en fonction de l’état de notre système d’intégration continue.

Quand c’est vert, tout va pour le mieux dans le meilleur des mondes !

Quand c’est orange, c’est qu’un déploiement est en cours :

Une fois le déploiement terminé, ça redevient vert. Mais si le déploiement échoue, le background devient rouge et tout le monde le voit :

Un déploiement a raté, il va falloir regardé ça.

Visualisation Kanban & Trello

Pour connaître le nombre de cartes de chaque liste en permanence, j’applique un filtre sur * afin de ne masquer aucune carte.

Soit dit en passant, je ne sais pas pourquoi le nombre de cartes d’une liste ne s’affiche que lorsqu’un filtre est activé.

J’utilise également une extension Chrome pour coloriser le background des listes en fonction du nombre de cartes. Si la limite de WIP est atteinte, c’est jaune. Si on dépasse, c’est rouge. Ce n’est pas indispensable, mais c’est pas mal pour comprendre l’état du flow de visu.

Existe également une extension Chrome qui semble faire tout cela : CardCounter for Trello, mais je ne l’ai pas encore testé donc je ne sais pas ce que ça vaut.

Une autre extension assez pratique : Card color titles qui affiche les titres des labels directement sur les cartes.

Enfin, Ollert est un outil de visualisation assez complet qui vous permettra, notamment, de tracer le Cumulative Flow Diagram de votre tableau sur une période donnée.

Board « Calendar »

Pour finir, une petite anecdote sur une board que nous avions appelé « Calendar ».

Elle répondait à la problématique suivante : que faire quand une tâche doit être réalisée à un moment donné, pas avant, pas après. Autrement dit, une tâche qui ne passe pas dans un flow.

Nous avions alors mis en place une board TODO > Doing > Done avec le power-up calendar activé. Chaque carte était attribuée à quelqu’un et était planifiée à une date précise. Ce qui répondait parfaitement au besoin.

Finalement, il y a eu de moins en moins de cartes de ce genre à mesure que l’équipe s’est rôdée avec Kanban et que l’organisation a évolué jusqu’à son état actuel. Chaque cas « unique, qui ne peut pas fonctionner avec un système Kanban » (souvent, des tâches marketing / business d’ailleurs) a finalement trouvé sa place dans le flow à mesure que la philosophie Kanban a été intégrée.

Et finalement, j’ai pu fermer cette board devenue inutile… À la demande de l’équipe !

Kanban and Game Development with Trello

Tue, 26 Jan 2016 00:00:00 GMT

Context

Metidia, a start-up developing video games

I’m associate in a parisian start-up called Metidia.

Concretely, we build video games about consumer goods because we want to change the online selling world. Thus, we work on Vinoga: a Facebook social-farming game − think “FarmVille”, “Hay Day” − which is about wine. You are a winemaker, discovering the steps that will make you produce actual bottles across your journey. While your vines are growing you can even take a look at your wine list, customize, order and then enjoy for real the great vintages you have virtually produced.

Our challenge, as a start-up, is to iterate from an initial idea to a business model that works, before we get out of resources.

And there, among every roles you typically accumulate within a start-up, I’m the one responsible of the production part: ensure the team makes stuff happen, tests hypothesis and builds the game that will meet clients-players needs.

Our production team is composed from 1 Game Designer, 1 Game Artist and 2/3 Developers. Although we were 2 at the beginning, without much organization, we quickly had to adapt not to repeat mistakes of the early days − produced assets that become obsolete before being integrated ; poor code quality that should be reworked because of bugs…

We took advantage of our flexibility to adopt de facto the Agile principles. At the beginning, it was all trial and error. We learned a lot from Scrum to organize ourselves, but it reveals to be too heavy, not suited to our early needs and context.

At the end, I think that Agile is a buffet from which you should take the best.

We progressively composed a process that is adapted to us, pecking best practices that worked for us.

Finally, Kanban appeared to be particularly efficient for the team: flexible enough to continuously adapt ; still robust enough to avoid people disperse their energy around − which is not quite easy when you deal with creative minds.

Kanban, what is that?

To put it simply, Kanban is a “visual process-management system that tells what to produce, when to produce it, and how much to produce”.

The heart of Kanban is to visualise the production process to set up a limited pull system of work in progress. That means you limit the number of parallel tasks for each step of your process. Whenever there is a free space, the downstream step will take an upstream task - that’s the pull system - to make the work flow, not the other way.

Concretely, here’s how would look a typical Kanban process: One day in Kanban land

Moving to Kanban is dead easy since you start with what you’ve got:

identify existing processes (eg: the production process, the player support process…)
decompose workflows of every identified process
setting limits to work in progress − simply start with what you’ve got

Then, the key is to progressively improve your flow with the team. This is Kaizen, an essential part of Kanban: the team regularly has a retrospective look to continuously and incrementally improve the way they work. This way, they can adapt themselves to the context, try new ideas, adapt to changes…

That’s the way we made Work In Progress (WIP) limits evolve for each process step, until we reach values that make us really productive - low WIP = high throughput − without being stuck… which is good for morale!

Big picture

We adopted Trello since the very beginning in 2013. Free, intuitive, easy onboarding, it is our virtual whiteboard and partner in crime which evolves along with our organization.

Trello boards are very flexible, which allows us to make changes through time regarding our needs.

Trello can also be used for remote teams, and it is much more than that. It’s whatever you need it to be, based on the projects you’re working on whether they are for different clients.

And so we may create and close diverse boards regarding projects we work on. These boards structure may vary regarding what’s needed: a temporary project managed with some GANTT because business needs it - thanks to the Elegantt extension ; a simple TODO > Doing > Done Kanban to handle a subproject ; etc.

All that aside, we have set up a board for each identified process:

Production
Business
Support
Communication

Each board represents a single activity that has its workflow.

In this post, I’ll just focus on the production board cogs.

The production board

The − Kanban − production board represents our production force, the work of the production team. This is valid, whatever should be produced: bug correction, new feature on Vinoga or another product, hotfix… Whatever should be delivered by the team.

This is an honest point of view of the work capacity of the team. That way we can prioritize everything we do and standardize the production process.

Our production board

Goals

The very first list of the board contains our key metrics: the 3/4 KPIs that really matter for us. This is for the team to always keep an eye on them. That’s a source of motivation!

We review these every month to understand where we are and decide where do we go.

This is also an opportunity to celebrate successes together, because that’s good for morale!

Templates

This list is mostly an utility: it contains cards that are templates which save our time.

Actually, we don’t really use “card templates” as we want to keep the card creation process simple to anyone that may have an idea. As anyone can create a card, it’d be utopian to imagine they’d duplicate the appropriate card whenever it happens, because it’s not intuitive at all.

However, we use these cards to hold checklists templates.

Indeed, Kanban advocates to “make process policies explicit”: anyone should be able to know whether or not a card is ready to move to the next step of the flow. This is why the team has agreed on − and make evolve − exit policies for each step of the production flow. And the best way we found to make it work with Trello is using checklists!

Example of a template for explicit exit policies

Thus, when we’re done with some card, we know that we have to create the exit checklist. Which is made easy with templates:

Simply copy a checklist template

Our trick to quickly retrieve your checklists templates is to name your card to have it appear at the top of the list.

The (Template) prefix is perfect for that.

Icebox / Backlog

How to handle the “Backlog” is certainly what took us the most time to figure out: where should we put ideas, incoming TODOs, without it becomes a heavy mess to deal with?

We tested a lot of alternatives, including using a “Planning” board just like UserVoice did. But what really worked for us was to include a “Backlog” list, directly in the production board.

Cards in this list are prioritized, which means the team will treat the card which is on the top as soon as possible. That way we can re-prioritize cards until the very last moment.

That’s deferring decisions as late as possible to be more efficient.

We used to limit the size of the backlog to avoid cards to pile up faster than we would be able to treat them. But we finally drop that limitation since the team has become able to self-manage. Cumulative Flow Diagram is enough to make us visualize the current tendency at a glance and understand if we’re adding more cards than reasonable.

Therefore, “Backlog” contains cards we decided to handle soon. They generally are related to one of the main goals we are focusing on.

However, I dare you to make a creative team stop having ideas! And to support this creativity, you should break down barriers. This is why “Icebox” exists!

Without any card limitation, it holds any idea or suggestion that wouldn’t necessarily be part of the backlog (eg: ideas to improve game monetization while current focus is on retention).

We regularly check these cards to move to the backlog those which become relevant, delete those which are not applicable anymore or even add some info and ideas to others.

Keeping this list into the board makes things easy and flexible. It gives us a mid-long term vision. Still, we don’t spend that much time on it because you know, as a start-up, the mid-long term may rapidly change.

Production workflow

Our production workflow

This concretely represents the different steps each card will pass through.

Each step has a WIP limit which is indicated in the list title.

Cards flow being “pulled”: whenever a step is completed, the card still there − with a little green label − until someone from the downstream step can take charge of it. All that, respecting WIP limits.

Exceptionally, some cards may not respect WIP limits. That may happen for an urgent one (eg: critical hotfix required in production) or a card waiting for some external dependency (eg: waiting for Facebook validation). In these cases, cards have an explicit red label. But these cases are rare.

Card Preparation

Cards are prepared for the rest of the flow.

That’s here we detail the card use case along with its SMART objective. Any card has an objective − why would it be there otherwise? Whether its a bug correction or a whole new feature, there should be a reason for us to deal with this card instead of another one. Furthermore, we determinate how we would be able to know if the objective is reached and what to do on success or failure.

Thus, we don’t lose that much time preparing cards that lie in the backlog. Only the main goal matters at that point. Then, we dig the idea into Card Preparation. We agree on the scope of the card or the way we split it into smaller ones − a game mechanics can generally be decomposed into smaller features we can implement one after the other.

Production

Here will happen the game design / spelling / arts / development of a card.

Anyone is free to use checklists to organize its work. Even to create a temporary board if needed.

For a while, we use to detail every production step − specs, arts, dev… − with a list. However, that was not flexible enough, nor realistic.

A single “Production” list gives us more latitude so developers can directly work hand-to-hand with game artists during integration for instance ; or whenever no game artist is available for a week, preventing “air bubbles” into the flow.

QA Tests

There, we will ensure that what we produced matches what was expected. A pair usually deals with this part to ensure the quality − the game designer, someone from the business team, another developer that didn’t code…

We also make sure that we are able to answer the SMART objective we defined.

If anything goes wrong, the card lies there and block the rest of the flow until it’s fixed. Thus, the team will better getting things done before starting new stuff. That makes everyone cares about the quality.

Mise en live (= release)

This is the release part, where what has been produced goes to production.

We continuously deploy everything. If needed, we use feature flipping to activate / deactivate any feature.

Live

Once released into production, cards are not done yet.

Remember that any card has an associated SMART objective the team agreed on? Well, once in production, we do analyse it.

That can be done when the card is released − that’s the case with most of bug fixes − or later if we need to collect some data − A/B tests, for instance. In the latter case, we set a due date and a responsible to the card.

When the analysis is done, the card is considered completed. We move it into the Live of the current month. Then we follow the scenario we forecasted regarding if the objective was reached or not. Objectives can be considered as our “assumptions” within the meaning of Lean Startup.

We do a monthly review of cards that were put to live = what we learned.

Lessons learned & Anecdotes

Here is a loose couple of stuff we learned or set up and that revealed useful to us.

Keep it simple

Well, that’s all about the KISS principle. Keep it in mind, really.

For example, I realized that the more I created boards to distinguish works, having specific workflow for every board just like UserVoice did, the less it was efficient for the team. The truth is that what is essential should be kept under your eyes to keep focus.

Otherwise? It wouldn’t be easily adopted, nor actually used by the team… because that’s not practical for them. Don’t overengineer things more than absolutely needed.

Concerning cards estimations…

… that’s a waste of time for us.

There are plenty of debates on the subject, which I won’t detail here.

But, in our case, we now have an efficient and fast “production line”, thanks to Kanban. We know our average speed to produce something, thanks to indicators. We do our best to homogenize the size of incoming cards and continuously ship changes to our game, focusing on what matters.

If a card is really urgent, you just need to put it at the top of the backlog and it will naturally be shipped to production within a known, reliable and reasonable delay − 8 calendar days so far, in average.

If that’s even more urgent and that couldn’t wait, then a red label will make it skip the line and be handled in priority − that’s the fast-line. Still, this kind of emergency is quite rare once you’ve got a production team that can introduce change as best and quick as possible.

Visual management

“Visualize” is one of the central pillars of Kanban specifically, and among other Agile practices in general.

Trello perfectly fulfill that need with power-ups such as GitHub, or through its API.

For instance, we do change the background color of the board regarding the state of our continuous integration system.

When it’s green, everything goes fine!

When it’s orange, then a deployment is occurring:

Once deploy is completed, it turns back to green. But if it has failed to deploy, background turns to red so everyone knows:

A deploy failed, we need to give it a look

Kanban & Trello visualisation

In order to know how much cards each list has, I do filter the board over * so I don’t actually hide any card.

With that said, I actually don’t know why the number of cards in a list only shows up when you’re filtering.

I also use a Chrome extension to give some color to lists background regarding the number of cards in it. If the WIP limit you set is reached, it becomes yellow. If the limit is exceeded, it turns red. This is not truly a must-have, but that’s really helpful to understand the state of the flow at a glance.

There seems to have a Chrome extension that does all of this: CardCounter for Trello, but since I didn’t tested it, I can’t recommend it.

Another very useful extension: Card color titles which displays labels titles right on the cards.

And then, Ollert which is a nice exhaustive visualisation tool. It can draw the Cumulative Flow Diagram for a defined period of your board, among other stuff.

Board “Calendar”

Let’s end this post with a story about a board we named “Calendar”.

It was here for a purpose: what do we do for a task that should be done at a specific date, not before, nor after? In other words, a task that simply can’t be put into the flow.

So we set up this basic TODO > Doing > Done board with the calendar power-up enabled. Each card was assigned to someone and a due date was set. Which was all we needed.

At the end, there were less and less cards of this kind as the team get trained with the Kanban mindset and the organization evolved to what it is today. Every use case that used to be “unique, which can’t work in a Kanban system” − there were often marketing / business tasks by the way − finally found its way into the flow as the Kanban philosophy was understood.

And, at last, I deleted this board that became useless… upon the team request!

Plop — un micro-générateur pour se simplifier la vie au quotidien

Thu, 26 Nov 2015 00:00:00 GMT

Vidéo & Slides

J’ai présenté ce talk le 21 décembre 2015 au meetup Node.js Paris Chapitre 3 / Conférence 2.

Kezako plop ?

Plop c’est un petit paquet node qui permet de se simplifier la vie quand on veut créer un nouveau controller / router / helper / …

Bah créer un nouveau controller c’est facile : je copie-colle le code d’un autre controller et je supprime les lignes dont je ne me sers pas. Tadaaa !

Certes, mais viennent un certain nombre de questions légitimes :

Quel “autre” controller ? Le plus récent ? Le “mieux” codé ? Y a-t-il un controller de référence ?
Si je ne suis pas (encore) un expert du projet en question, comment répondre au point précédent ?
Comment m’assurer que je ne me trompe pas en nommant le nouveau fichier ? En supprimant les lignes qui sont “inutiles”, selon moi ?
Est-ce-que je dois déclarer ce nouveau controller quelque part dans un fichier existant ? Lequel ? Comment ?

Trouver un bon fichier, l’ouvrir, copier son contenu, créer un nouveau fichier, coller le contenu, supprimer les lignes inutiles… C’est répétitif, propice aux erreurs et ça n’a pas beaucoup de valeur ajoutée. En plus, ça peut prendre un peu de temps. Surtout, c’est fréquent !

Ce serait vachement mieux à la place d’écrire plop dans son terminal, répondre à 2 questions et BIM, c’est fait !

Simple et efficace. Toujours tenté(e) par l'option copier-coller ?

C’est exactement ce que nous allons voir ici.

Setup

Installation

Plop étant un paquet node, npm install -g plop et vous pouvez commencer à jouer.

On peut aussi l’installer localement sur le projet en le rajoutant aux dépendances : npm install --save-dev plop.

Puis ajoutez-le aux scripts de votre package.json pour pouvoir le lancer avec npm run plop :

{
  "name": "your-awesome-project",
  "description": "This is an awesome project, isn't it?",

  "dependencies": {},
  "devDependencies": {
    "plop": "1.0.1"
  },

  "scripts": {
    "plop": "plop"
  }
}

Voilà !

Configuration

Plop se base sur un plopfile.js.

C’est le fichier de configuration standard, que je vous suggère de placer à la racine du projet :

module.exports = plop => {
  // C'est ici qu'on va configurer nos générateurs
}

Plop va également se baser sur des templates qui peuvent soit être inlined dans le fichier de configuration, soit placés dans des fichiers séparés. Je vous suggère de les placer dans un dossier plop-templates/, à la racine du projet également.

All inclusive FTW

Comme vous l’aurez compris : le générateur et les templates sont embarqués dans le projet, à l’instar des tests ou du task runner (brunch, gulp, grunt…).

Cela a des avantages considérables sur un générateur Yeoman personnalisé :

un seul dépôt à maintenir
tout est déjà embarqué dans le projet, nul besoin d’installer yeoman et ledit générateur pour pouvoir s’en servir
mettre à jour un template est trivial, pas besoin de publier une nouvelle version du générateur et s’assurer que tout est à jour avant de l’utiliser

Finalement, là où un développer un générateur Yeoman spécifique au projet est overkill, plop est parfaitement adapté. Léger, près du code source, il sera plus facilement adopté, maintenu et, en fin de compte, utilisé.

Notre premier générateur

Pour déclarer un générateur, plop nous fournit la méthode setGenerator :

module.exports = plop => {
  // On déclare un nouveau générateur appelé "module"
  plop.setGenerator('module', {
    // Décrit succintement ce que fait le générateur
    // pour s'y retrouver.
    description: 'Create a new module',

    // Récupère les inputs de l'utilisateur.
    // C'est Inquirer.js qui fait le job ici.
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is your module name?',
      },
    ],

    // Liste des actions à faire.
    // Ici, on "add" de nouveaux fichiers à partir
    // de nos templates.
    actions: [
      {
        type: 'add',
        path: 'app/modules/{{camelCase name}}.js',
        templateFile: 'plop-templates/module.js',
      },
      {
        type: 'add',
        path: 'app/tests/{{camelCase name}}.tests.js',
        templateFile: 'plop-templates/module.tests.js',
      },
    ],
  })
}

Prompts

La partie prompts est directement déléguée à Inquirer.js.

Vous pouvez donc vous référez à leur documentation pour découvrir tout ce que vous pouvez faire (type des questions, filtre d’output, validation d’input…).

On peut ainsi imaginer des choses un peu plus complexes :

import { trimRight, isEmpty } from 'lodash'

const ensurePlural = text => trimRight(text, 's') + 's'

const isNotEmptyFor = name => {
  return value => {
    if (isEmpty(value)) return name + ' is required'
    return true
  }
}

module.exports = plop => {
  plop.setGenerator('module', {
    // …

    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is your module name?',
        validate: isNotEmptyFor('name'),
        filter: ensurePlural,
      },
    ],

    // …
  })
}

validate va s’assurer que le nom donné pour le module n’est pas vide.

filter me permet de formaliser l’output : tous les noms des modules doivent se terminer par un s. Ainsi, si par inadvertance je nomme mon module calendar, je suis assuré que la variable name vaudra calendars pour la suite.

Actions

Une fois qu’il sait tout, plop va réaliser l’ensemble des actions qu’on lui demande. Il dispose à ce moment là des variables que lui fournit inquirer.

Les actions, comme les templates, sont parsées avec Handlebars. Si vous avez compris son fonctionnement, vous savez déjà utiliser plop.

Ainsi {{name}} correspond à la réponse donnée au prompt, validée et filtrée au préalable. Il me suffit de la placer où bon me semble, dans le chemin du fichier créé et/ou son template.

Il faut savoir qu’il y a 2 types d’actions supportés pour le moment :

"add" qui va créer un nouveau fichier au niveau du path indiqué (relatif à plopfile.js)
"modify" qui va modifier le fichier situé au niveau du path. Il va remplacer la RegExp définie dans pattern par le template

Pour les 2 actions on peut soit utiliser un template inline via template, soit spécifier le chemin du template à utiliser via templateFile.

Un exemple concret

Ça peut donner quelque chose du genre :

const modulePath = 'app/modules/{{camelCase name}}.js'

module.exports = plop => {
  plop.setGenerator('model', {
    // …

    actions: [
      // Ajoute un nouveau model + boilerplate de tests.
      {
        type: 'add',
        path: 'app/modules/{{camelCase name}}.model.js',
        templateFile: 'plop-templates/model.js',
      },
      {
        type: 'add',
        path: 'app/tests/{{camelCase name}}.model.tests.js',
        templateFile: 'plop-templates/model.tests.js',
      },

      // Modifie le module pour y injecter le model créé.
      // Tout fonctionne avec un replace de RegExp.
      {
        type: 'modify',
        path: modulePath,
        pattern: /(\/\/ IMPORT MODULE FILES)/g,
        template: '$1\nimport Model from "./{{camelCase name}}.model";',
      },
      {
        type: 'modify',
        path: modulePath,
        pattern: /(const namespace = "\w+";)/g,
        template: '$1\n\nModel = Model.extend( { namespace: namespace } );',
      },
    ],
  })
}

À partir du template plop-templates/model.js :

/**
 * TODO - Describe what your model does.
 *
 * @class {{pascalCase name}}.Model
 * @module {{pascalCase name}}
 * @constructor
 */
import { Model } from 'backbone'

export default Model.extend({
  initialize() {
    // Executed on model initialization
  },
})

Si {{name}} vaut calendars, alors plop va créer le fichier app/modules/calendars.model.js suivant :

/**
 * TODO - Describe what your model does.
 *
 * @class Calendars.Model
 * @module Calendars
 * @constructor
 */
import { Model } from 'backbone'

export default Model.extend({
  initialize() {
    // Executed on model initialization
  },
})

Et va transformer notre app/modules/calendars.js actuel :

import Module from 'core/module'
import _ from 'lodash'

// IMPORT MODULE FILES

const namespace = 'calendars'

export default Module.extend({
  initialize() {
    _.defaults(this.options, { isDisplayed: true })
  },

  onStart() {
    this.ready()
  },

  onReady() {
    // Do something when module is considered as ready
  },
})

Pour y insérer le model créé :

import Module from 'core/module'
import _ from 'lodash'

// IMPORT MODULE FILES
import Model from './calendars.model'

const namespace = 'calendars'

Model = Model.extend({ namespace: namespace })

export default Module.extend({
  initialize() {
    _.defaults(this.options, { isDisplayed: true })
  },

  onStart() {
    this.ready()
  },

  onReady() {
    // Do something when module is considered as ready
  },
})

Avec "add" et "modify" il est possible de faire un paquet de petites choses répétitives plus simplement.

Adapter les actions en fonction des réponses données

Vous pouvez également passer une fonction à actions. Cette fonction prend en paramètre les réponses de l’utilisateur et doit retourner le tableau des actions à effectuer.

L’intérêt c’est de pouvoir adapter les actions en fonction des réponses données.

Prenons l’exemple de la création d’un nouveau module :

module.exports = plop => {
  plop.setGenerator('module', {
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is the name of your module?',
        validate: isNotEmptyFor('name'),
        filter: ensurePlural,
      },
      {
        type: 'list',
        name: 'dataConfig',
        message: 'Tell me about the data, what do you need?',
        default: 'none',
        choices: [
          { name: 'Nothing', value: 'none' },
          { name: 'A Model', value: 'model' },
        ],
      },
    ],

    actions: data => {
      // Ajoute un nouveau module quoiqu'il en soit.
      let actions = [
        {
          type: 'add',
          path: 'app/modules/{{camelCase name}}/{{camelCase name}}.js',
          templateFile: 'plop-templates/module.js',
        },
        {
          type: 'add',
          path:
            'app/modules/{{camelCase name}}/tests/{{camelCase name}}.tests.js',
          templateFile: 'plop-templates/module.tests.js',
        },
      ]

      // Si l'on souhaite un modèle, alors on en ajoute un
      // dans la foulée.
      if (data.dataConfig === 'model') {
        actions = actions.concat([
          {
            type: 'add',
            path: 'app/modules/{{camelCase name}}.model.js',
            templateFile: 'plop-templates/model.js',
          },
          {
            type: 'add',
            path: 'app/tests/{{camelCase name}}.model.tests.js',
            templateFile: 'plop-templates/model.tests.js',
          },
        ])
      }

      // Retourne le tableau des actions à réaliser.
      return actions
    },
  })
}

Le générateur peut donc s’adapter aux réponses que l’on donne et prendre en compte un certain nombre de scénarios (un module avec un Model, une Collection + Model, avec une CollectionView ou bien une CompositeView…).

Helpers

Un petit point sur les helpers de templating de plop : ce sont ceux de Handlebars.

Il y a déjà un certain nombre de helpers fournis par plop. camelCase, par exemple, fonctionne ainsi : {{camelCase name}} avec name = "my awesome module" donne "myAwesomeModule".

Vous pouvez définir vos propres helpers dans le plopfile.js avec addHelper :

module.exports = plop => {
  plop.addHelper('upperCase', text => text.toUpperCase())

  // …
}

On vient de créer un helper upperCase que l’on pourra utiliser dans les actions et les templates : {{upperCase name}}.

Just use it

Et c’est tout, il ne reste plus qu’à lancer npm run plop (ou plop, si vous l’avez installé globalement) et se laisser guider.

On peut aussi directement appeler un générateur avec npm run plop [generatorName].

À l’usage plop est rapide et efficace tout comme Yeoman. Par contre, il est bien plus léger et simple à maintenir.

Retour d’expérience en production

À l’heure actuelle, j’utilise plop avec mon équipe sur le projet Vinoga. Ses fonctionnalités conviennent parfaitement à nos use cases.

J’avais développé un générateur Yeoman auparavant, largement inutilisé par l’équipe en pratique.

Vraiment, plop est le genre d’outil qui nous fait gagner 10 minutes par-ci par-là au quotidien. Et lancer plop module dans sa console, c’est plutôt cool \o/

Plop — a micro-generator to ease your daily life

Thu, 26 Nov 2015 00:00:00 GMT

What’s plop?

Plop is a little node package that will ease your life whenever you need to create a new controller / router / helper / …

Hey, that’s damn easy to create a new controller: copy-paste another controller code, delete specific lines you won’t use. Tadaaa!

Well, now pop a bunch of legitimate questions:

Which “other” controller do you speak about? The more recent? The “best” coded? Is there any reference controller around there?
How can I get the previous point if I’m not — yet — an expert of the project codebase?
How can I ensure I’m correct when I name the new file? When I delete lines I consider “useless”?
Do I need to declare this new controller in some existing file? Which one? How?

Find a good file, open it, copy its content, create a new file, paste the content, delete useless lines… It’s repetitive, error prone and doesn’t have a lot of added value. And that could take some time. Most of all, that’s frequent!

It would just be awesome to write plop in your terminal, answer 2 questions and BIM, you’re all set!

Quick, neat. Still tempted with the copy-paste option?

That’s exactly what I’m talking about here.

Setup

Installation

As a node package, npm install -g plop and you’re ready to play with plop.

You also can install it locally to the project, adding it to dependencies: npm install --save-dev plop.

Then add it to your package.json scripts so you can run it with npm run plop:

{
  "name": "your-awesome-project",
  "description": "This is an awesome project, isn't it?",

  "dependencies": {},
  "devDependencies": {
    "plop": "1.0.1"
  },

  "scripts": {
    "plop": "plop"
  }
}

Voilà!

Configuration

Plop uses a simple plopfile.js.

Here’s the standard configuration file I’d suggest you to put at the root of the project:

module.exports = plop => {
  // Here we'll define our generators
}

Plop will also use templates that can either be inlined within the configuration file, or put in separate files. My suggestion is to put them into a plop-templates/ folder, at the root of the project too.

All inclusive FTW

As you’d guess: both generator and templates are embedded in the project, just like your tests or task runner (brunch, gulp, grunt…).

This has tremendous advantages over a customized Yeoman generator:

a single repo to maintain them all
everything is embedded, no need for installing yeoman and a generator to use it
update a template is dead easy, you don’t a to publish a new version of your generator and make sure everyone is up-to-date before using it

In a nutshell, when a project-specific Yeoman generator may sound overkill, plop fits perfectly. Lightweight, close to source code, it will be easier to adopt, maintain and, at the end, it will be used.

Our first generator

To declare a new generator, plop provides you setGenerator:

module.exports = plop => {
  // We declare a new generator called "module"
  plop.setGenerator('module', {
    // Succintly describes what generator does.
    description: 'Create a new module',

    // Get inputs from the user.
    // That's Inquirer.js doing the job behind the hood.
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is your module name?',
      },
    ],

    // List of actions to take.
    // Here we "add" new files from our templates.
    actions: [
      {
        type: 'add',
        path: 'app/modules/{{camelCase name}}.js',
        templateFile: 'plop-templates/module.js',
      },
      {
        type: 'add',
        path: 'app/tests/{{camelCase name}}.tests.js',
        templateFile: 'plop-templates/module.tests.js',
      },
    ],
  })
}

Prompts

The prompts part is delegated to Inquirer.js.

You can just refer to their documentation to learn whatever you can do — questions types, output filter, input validation…

You can imagine doing some not trivial stuff:

import { trimRight, isEmpty } from 'lodash'

const ensurePlural = text => trimRight(text, 's') + 's'

const isNotEmptyFor = name => {
  return value => {
    if (isEmpty(value)) return name + ' is required'
    return true
  }
}

module.exports = plop => {
  plop.setGenerator('module', {
    // …

    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is your module name?',
        validate: isNotEmptyFor('name'),
        filter: ensurePlural,
      },
    ],

    // …
  })
}

validate will ensure the given module name is not empty.

filter allow you to standardize the output: here module names should end with an s by convention. Even if I do it wrong and give calendar as the module name, I can be sure the name variable will be calendars.

Actions

Now it knows everything it needs, plop will run every actions you configured. It can use every variables that inquirer did transmit.

Actions, just like templates, are parsed with Handlebars. If you understand how it works, you know how to use plop.

Therefore {{name}} is the answer given to the prompt, validated and filtered previously. You can drop it wherever needed, in the created file path and/or its template.

There are 2 types of actions that are supported yet:

"add" that will create a new file into the given path — which is relative to plopfile.js
"modify" that will modify the file located at given path. It will replace the RegExp you provided in pattern with the template you provide

Both actions can either use an inlined template via template, or retrieve it from the path you set via templateFile.

A concrete example

Let’s imagine that kind of implementation:

const modulePath = 'app/modules/{{camelCase name}}.js'

module.exports = plop => {
  plop.setGenerator('model', {
    // …

    actions: [
      // Add a new model + tests boilerplate.
      {
        type: 'add',
        path: 'app/modules/{{camelCase name}}.model.js',
        templateFile: 'plop-templates/model.js',
      },
      {
        type: 'add',
        path: 'app/tests/{{camelCase name}}.model.tests.js',
        templateFile: 'plop-templates/model.tests.js',
      },

      // Modify the module file to inject created model.
      // This is basically RegExp replacement.
      {
        type: 'modify',
        path: modulePath,
        pattern: /(\/\/ IMPORT MODULE FILES)/g,
        template: '$1\nimport Model from "./{{camelCase name}}.model";',
      },
      {
        type: 'modify',
        path: modulePath,
        pattern: /(const namespace = "\w+";)/g,
        template: '$1\n\nModel = Model.extend( { namespace: namespace } );',
      },
    ],
  })
}

Then, let’s say you have the plop-templates/model.js template:

/**
 * TODO - Describe what your model does.
 *
 * @class {{pascalCase name}}.Model
 * @module {{pascalCase name}}
 * @constructor
 */
import { Model } from 'backbone'

export default Model.extend({
  initialize() {
    // Executed on model initialization
  },
})

Considering {{name}} is calendars, then plop will create the following app/modules/calendars.model.js file:

/**
 * TODO - Describe what your model does.
 *
 * @class Calendars.Model
 * @module Calendars
 * @constructor
 */
import { Model } from 'backbone'

export default Model.extend({
  initialize() {
    // Executed on model initialization
  },
})

And will also transform your current app/modules/calendars.js module file:

import Module from 'core/module'
import _ from 'lodash'

// IMPORT MODULE FILES

const namespace = 'calendars'

export default Module.extend({
  initialize() {
    _.defaults(this.options, { isDisplayed: true })
  },

  onStart() {
    this.ready()
  },

  onReady() {
    // Do something when module is considered as ready
  },
})

To insert the reference to the created model:

import Module from 'core/module'
import _ from 'lodash'

// IMPORT MODULE FILES
import Model from './calendars.model'

const namespace = 'calendars'

Model = Model.extend({ namespace: namespace })

export default Module.extend({
  initialize() {
    _.defaults(this.options, { isDisplayed: true })
  },

  onStart() {
    this.ready()
  },

  onReady() {
    // Do something when module is considered as ready
  },
})

With "add" and "modify" you can ease a lot of small repetitive things.

Adapt actions to given answers

You can pass a function to actions. This function will take user’s answers as a parameter and should return the array of actions to take.

This way you can adapt actions to given answers.

Let’s consider this example of new module creation:

module.exports = plop => {
  plop.setGenerator('module', {
    prompts: [
      {
        type: 'input',
        name: 'name',
        message: 'What is the name of your module?',
        validate: isNotEmptyFor('name'),
        filter: ensurePlural,
      },
      {
        type: 'list',
        name: 'dataConfig',
        message: 'Tell me about the data, what do you need?',
        default: 'none',
        choices: [
          { name: 'Nothing', value: 'none' },
          { name: 'A Model', value: 'model' },
        ],
      },
    ],

    actions: data => {
      // Add a new module, whatever happens.
      let actions = [
        {
          type: 'add',
          path: 'app/modules/{{camelCase name}}/{{camelCase name}}.js',
          templateFile: 'plop-templates/module.js',
        },
        {
          type: 'add',
          path:
            'app/modules/{{camelCase name}}/tests/{{camelCase name}}.tests.js',
          templateFile: 'plop-templates/module.tests.js',
        },
      ]

      // If you wish a Model, then we add a Model.
      if (data.dataConfig === 'model') {
        actions = actions.concat([
          {
            type: 'add',
            path: 'app/modules/{{camelCase name}}.model.js',
            templateFile: 'plop-templates/model.js',
          },
          {
            type: 'add',
            path: 'app/tests/{{camelCase name}}.model.tests.js',
            templateFile: 'plop-templates/model.tests.js',
          },
        ])
      }

      // Return the array of actions to take.
      return actions
    },
  })
}

Your generator can adapt to many different scenarios (e.g: a module with a Model, a Collection + Model, with a CollectionView or a CompositeView…).

Helpers

A little note about templating helpers of plop: these are those from Handlebars.

You starts with a bunch of helpers plop gives you. camelCase, for instance, just works this way: {{camelCase name}} with name = "my awesome module" gives "myAwesomeModule".

You can define your own helpers within plopfile.js with addHelper :

module.exports = plop => {
  plop.addHelper('upperCase', text => text.toUpperCase())

  // …
}

We just created an upperCase helper we could use later in the actions and templates: {{upperCase name}}.

Just use it

There you go, just type npm run plop — or simply plop, if you made it global — then follow the guide.

You can also directly call a specific generator with npm run plop [generatorName].

Plop is fast and efficient to use, just like Yeoman. However, it’s far more lightweight and easier to maintain.

My experience feedback in production

As of the time of writing, I use plop with my team on the Vinoga project. Its features perfectly match our use cases.

I did wrote a Yeoman generator for the project before. It was concretely unused by the team.

Definitely, plop is the kind of tool that saves you 10 minutes here and there, every single day. And running plop module in your console, how cool is that \o/

Tester ses Behaviors Marionette.js

Mon, 23 Nov 2015 00:00:00 GMT

Contexte

Ceci est un talk que j’ai présenté le 10 novembre 2015 au meetup Backbone.js Paris S02E01.

Vidéo

Slides

Concrètement

Les problématiques

Lorsqu’on se dit qu’on va tester notre Behavior, la première problématique que l’on rencontre est généralement la suivante :

Mince, comment je fais pour instancier ma Behavior pour pouvoir tester son API ?

En fait, l’API d’une Behavior ce ne sont pas particulièrement les méthodes publiques qu’on y déclare. Celles-ci ne seront jamais appellées directement :

const Alert = Marionette.Behavior.extend({
  defaults: {
    title: 'Alert!',
    message: 'Not really urgent',
  },

  events: {
    click: 'emitAlert',
  },

  emitAlert() {
    alert(this.options.message)
  },
})

it('should emit an alert', () => {
  // => This won't work
  expect(Behavior.emitAlert()).toEmitAnAlert()
})

Une Behavior réagit à des événements (interactions DOM, trigger de la vue, etc.).

Pour tester une Behavior, il faut donc déclencher ces événements puis observer l’impact de la Behavior sur le système pour voir si celle-ci a réagit correctement. Les Behaviors fonctionnant par effets de bord, c’est bel et bien ce qu’il faut tester.

Une Behavior est déclarée et instanciée dans le contexte d’une vue :

const ShareView = Marionette.ItemView.extend({
  template: '#card',

  behaviors: {
    AlertOnShare: {
      behaviorClass: AlertBehavior,
      title: 'Shared',
      message: 'Your message has been shared!',
    },
  },
})

Pour tester une Behavior, il faut donc commencer par instancier une vue dans laquelle celle-ci est déclarée.

OK ! Donc je vais mock une vue en y déclarant ma Behavior pour pouvoir la tester.

describe('Alert Behavior', () => {
  let view

  beforeEach(() => {
    view = Marionette.ItemView.extend({
      template: _.template(''),

      behaviors: {
        Alert: {
          behaviorClass: AlertBehavior,
          title: 'Title',
          message: 'My message.',
        },
      },
    })
  })

  // …
})

C’est une possibilité.

Cependant, je n’ai pas vraiment le comportement de la Behavior dans le contexte des vues de mon application. Ce n’est pas nécessairement grave puisque nous parlons de tests unitaires. Simplement, cela demande beaucoup de cérémonie pour mock tout ce qu’il faut :

mock une vue avec les paramètres par défaut
mock une vue avec des paramètres configurés
mock tout ce qui doit être testé (template, events, triggers…)

Une autre solution consiste à tester la Behavior instanciée dans chacunes des vues de notre application, directement dans les tests de celles-ci en fait.

OK ! Je vais tester la Behavior dans chacune de mes vues… Mais, mais… Et la duplication ?!

Effectivement, si on commence par tester le comportement de nos Behaviors dans le contexte de chacune de nos vues, on se retrouve à dupliquer les tests. Sachant que le principe de la Behavior c’est d’isoler un ensemble de comportements de vue pour ne pas avoir à le dupliquer, c’est un peu dommage de perdre ça côté tests.

Comment on s’en sort ?

Dépôt GitHub pour illustrer la solution proposée

L’idée consiste à refactor les tests d’une Behavior dans une fonction qui prend un context en paramètre.

function addOnClickTests(context) {
  let model, view

  beforeEach(() => {
    model = new context.ModelClass()
    view = new context.ViewClass({ model: model })
  })

  it('should increase the model size by 1 when we click on the view', () => {
    model.set('size', 1)

    view.$el.trigger('click')

    expect(model.get('size')).toBe(2)
  })
}

Cette factory embarque les tests de la Behavior et les déroule dans un contexte particulier.

Ceci nous permet de l’instancier dans le contexte de notre vue, avec les paramètres qui vont bien :

describe('Like View', () => {
  const View = LikeView.extend({ template: _.template('') })

  describe('AddOnClick Behavior', () => {
    addOnClickTests({ ViewClass: View, ModelClass: LikeModel })
  })
})

Oui, mais ici tu testes les paramètres par défaut de la Behavior : « increase the model size by 1 ». Comment tester des paramètres en particulier ? On les passe dans le contexte ? Du coup, on fait à nouveau de la duplication, autant mock la vue complètement.

C’est effectivement la raison pour laquelle Marionette expose publiquement un tableau des Behaviors instanciées d’une vue dans son attribut _behaviors depuis la v2.2.0.

L’astuce consiste donc à retrouver l’instance de la Behavior dans le contexte de la vue afin de pouvoir variabiliser les tests en fonction des paramètres avec lesquels la Behavior a été instanciée.

Pour cela, je déclare un id à mes Behaviors afin de pouvoir les retrouver facilement :

const OnClick = Marionette.Behavior.extend({
  id: 'addOnClick',

  defaults: {
    propertyToIncrease: 'size',
    increaseStep: 1,
  },

  events: {
    click: 'add',
  },

  add() {
    // increase `propertyToIncrease` by `increaseStep`
  },
})

function addOnClickTests(context) {
  let model, view, behavior, options

  beforeEach(() => {
    model = new context.ModelClass()
    view = new context.ViewClass({ model: model })

    // Retrieve instantiated behavior and its actual options under this context.
    behavior = _.findWhere(view._behaviors, { id: 'addOnClick' })
    options = behavior.options

    model.set(options.propertyToIncrease, 1)
  })

  it('should be instantiated', () => {
    expect(behavior).not.toBeUndefined()
  })

  it('should increase the model value when we click on the view', () => {
    var expectedValue =
      model.get(options.propertyToIncrease) + options.increaseStep

    view.$el.trigger('click')

    expect(model.get(options.propertyToIncrease)).toBe(expectedValue)
  })
}

Pour résumer

on teste l’API de la Behavior = son impact sur le système en réaction à des événements
on décrit nos tests de Behavior dans une factory qui prend un contexte en paramètre
on embarque nos tests dans chacune de nos vues en y passant le bon contexte
on utilise this.view._behaviors pour retrouver la Behavior (avec un id par exemple) et ses paramètres d’instanciation dans le contexte de la vue

Testing Marionette.js Behaviors

Mon, 23 Nov 2015 00:00:00 GMT

Context

This is a talk I gave on November 10th, 2015 at meetup Backbone.js Paris S02E01.

Video (FR)

Slides

Concretely

Problems

When you want to test your Behavior, the first problem that generally comes up is:

Damn, how to I instantiate my Behavior so I can test its API?

In fact, the Behavior API are not that much public methods you declared inside. These never are directly called:

const Alert = Marionette.Behavior.extend({
  defaults: {
    title: 'Alert!',
    message: 'Not really urgent',
  },

  events: {
    click: 'emitAlert',
  },

  emitAlert() {
    alert(this.options.message)
  },
})

it('should emit an alert', () => {
  // => This won't work
  expect(Behavior.emitAlert()).toEmitAnAlert()
})

A Behavior reacts to events — DOM interactions, trigger from the view, etc.

If you want to test a Behavior you then have to trigger these events then observe the Behavior’s impacts on the system to check if it reacted appropriately. Behaviors work with side effects, this is what you need to test.

A Behavior is declared and instantiated within the context of a view:

const ShareView = Marionette.ItemView.extend({
  template: '#card',

  behaviors: {
    AlertOnShare: {
      behaviorClass: AlertBehavior,
      title: 'Shared',
      message: 'Your message has been shared!',
    },
  },
})

To test a Behavior, you then need to instantiate a view in which the Behavior is declared.

OK! Then I’ll mock a view with my Behavior declared so I can test it.

describe('Alert Behavior', () => {
  let view

  beforeEach(() => {
    view = Marionette.ItemView.extend({
      template: _.template(''),

      behaviors: {
        Alert: {
          behaviorClass: AlertBehavior,
          title: 'Title',
          message: 'My message.',
        },
      },
    })
  })

  // …
})

This is an option.

However, you won’t have the Behavior actually behave within the context of your application’s views. This is not necessarily wrong since we’re talking about unit tests here. But that requires a lot of ceremony to mock whatever should be:

mock a view with default parameters
mock a view with configured parameters
mock whatever should be tested — template, events, triggers…

Another solution would be to test the instantiated Behavior within each view of our applicaation, directly in these views tests actually.

OK! So I’ll test the Behavior within each of my views… But well… what about duplication?!

Yep, if you go testing how your Behaviors behave for every view’s context, you will duplicate tests. That would be a pitty for something which is supposed to isolate views behaviors so you don’t duplicate code.

What can we do then?

GitHub repo to illustrate the proposed solution

The idea is to refactor Behavior’s tests into a function that will take context as a param.

function addOnClickTests(context) {
  let model, view

  beforeEach(() => {
    model = new context.ModelClass()
    view = new context.ViewClass({ model: model })
  })

  it('should increase the model size by 1 when we click on the view', () => {
    model.set('size', 1)

    view.$el.trigger('click')

    expect(model.get('size')).toBe(2)
  })
}

This factory embeds tests of your Behavior and run them within a specific context.

This allows you to instantiate tests with the context of your view, providing correct parameters:

describe('Like View', () => {
  const View = LikeView.extend({ template: _.template('') })

  describe('AddOnClick Behavior', () => {
    addOnClickTests({ ViewClass: View, ModelClass: LikeModel })
  })
})

Sure, but what you’re doing here is testing default parameters of the Behavior: « increase the model size by 1 ». How to test specific parameters? Should we pass them through the context? If so, that’s just duplication again. We’d better completely mock the view at the end.

That’s exactly why Marionette is publicly exposing the array of instantiated Behaviors of a view in its _behaviors attribute since v2.2.0.

The trick is to be able to retrieve your Behavior instance in the view context so you can adapt tests regarding parameters that it actually uses.

I specify an id to my Behaviors for that, so I can retrieve them easily:

const OnClick = Marionette.Behavior.extend({
  id: 'addOnClick',

  defaults: {
    propertyToIncrease: 'size',
    increaseStep: 1,
  },

  events: {
    click: 'add',
  },

  add() {
    // increase `propertyToIncrease` by `increaseStep`
  },
})

function addOnClickTests(context) {
  let model, view, behavior, options

  beforeEach(() => {
    model = new context.ModelClass()
    view = new context.ViewClass({ model: model })

    // Retrieve instantiated behavior and its actual options under this context.
    behavior = _.findWhere(view._behaviors, { id: 'addOnClick' })
    options = behavior.options

    model.set(options.propertyToIncrease, 1)
  })

  it('should be instantiated', () => {
    expect(behavior).not.toBeUndefined()
  })

  it('should increase the model value when we click on the view', () => {
    var expectedValue =
      model.get(options.propertyToIncrease) + options.increaseStep

    view.$el.trigger('click')

    expect(model.get(options.propertyToIncrease)).toBe(expectedValue)
  })
}

To sum it up

test the API of your Behavior = its impact on the system, reacting to some events
describe your Behavior tests in a factory that takes a context as a parameter
embed your tests in each of your views tests, using the according context
use this.view._behaviors to retrieve your Behavior — you can use an id for that — and its actual paremeters within the context of the view

Chaining et composition de fonctions avec lodash / underscore

Thu, 25 Jun 2015 00:00:00 GMT

Contexte

Ceci est un talk que j’ai présenté le 23 juin 2015 au meetup Backbone.js Paris S01E07.

Slides

Functions chaining and composition with lodash / underscore

Thu, 25 Jun 2015 00:00:00 GMT

Context

This is a talk I gave last June 23rd, 2015 at meetup Backbone.js Paris S01E07.

Slides

Héritage, composition et Backbone.js

Fri, 19 Jun 2015 00:00:00 GMT

“Favor objects composition over inheritance”

Dans la Programmation Orientée Objet (POO), on crée un certain nombre d’objets avec leur structure de données et les méthodes qui composent leur interface. Pour décider de comment découper nos objets, on suit le Single Responsibility Principle (SRP) : chaque objet doit avoir une seule et unique raison de changer.

Pour faire des choses intéressantes, il faut combiner ces objets.

Or, en gros, il existe 2 types de relations dans le modèle objets : l’héritage et la composition.

On peut faire l’analogie avec un arbre généalogique :

l’héritage, c’est comme une naissance : quand ça arrive, c’est pour la vie.
la composition c’est comme un mariage : ça arrive au cours de l’existence des objets et ça peut changer. Les objets peuvent se séparer et trouver de nouveaux partenaires avec qui s’associer. On notera néanmoins que les objets ne sont pas monogames.

Source: Object Design - Roles, Responsibilities and Collaborations

“Heritage” all the things!

Le premier réflexe des développeurs JavaScript consiste souvent à tenter de reproduire les règles d’héritage pseudo-classique.

On se retrouve alors vite avec des new un peu partout et des chaînes d’héritage longues comme le bras. Ça produit souvent quelque chose très difficile à maintenir.

Il est vrai qu’en Java on dispose de tout ce qu’il faut pour faire de l’héritage avec des classes, des interfaces, etc.

Ce n’est pas le cas en JavaScript.

Keep It Simple, Seriously

En JavaScript, la base, c’est l’héritage de prototype.

Si on oublie le jargon technique, disons qu’on a tout simplement des objets qui peuvent se lier à d’autres objets (OLOO).

Du coup, il est vachement plus simple d’encapsuler les méthodes d’une même logique dans un objet, puis de simplement retourner cet objet. Au besoin, on peut aussi créer une fonction qui va retourner un objet (ce qu’on appelle une factory).

Cet objet on va le prendre, éventuellement le composer avec d’autres, pour former le prototype avec lequel on va instancier notre classe. Tout simplement.

Pour résumer : plutôt que de créer des chaînes d’héritage plus ou moins bancales à grands coups de constructeurs, créez simplement vos objets et composez les pour former un prototype avec lequel vous allez instancier votre classe.

Concatenative inheritance

Quelqu’un m’a fait très justement remarqué que ce dont je vous parle ici s’appelle l’héritage multiple, plutôt que d’object composition au sens propre du terme.

Object composition fait référence au fait de faire pointer les attributs de notre objet vers des instances d’autres classes.

Il n’y a pas d’héritage multiple à proprement parler en JavaScript. Mais le fait de composer différents prototypes pour en former un nouveau est la notion qui s’en rapproche, ce qui peut générer de la confusion. On parle de “composer des prototypes”, ce qui est le cas, mais pas dans le sens de la composition d’objets…

Voici pour une explication plus concrète : Composition, Inheritance, and Aggregation in JavaScript

Du coup, nous appellerons ça la concatenative inheritance, à la manière d’Eric Eliott.

Sur un exemple concret

Contexte

Depuis quelques temps déjà, je travaille à temps plein sur Vinoga, un jeu de social farming sur le vin, développé en HTML5.

Entre autres bibliothèques, nous utilisons Backbone.js pour découpler simplement nos vues de nos données.

Prenons donc un cas concret : les éléments sur la carte.

En posant les choses, on se rend vite compte qu’il y a 2 types d’éléments :

les Props qui sont les éléments de décor (arbres, rochers, chemins…)
les Buildings qui sont les bâtiments du jeu (cuverie, château…)

Une différence parmi d’autres, mais notable à ce stade : les Buildings sont constructibles (depuis le menu de construction), les Props ne le sont pas (ils sont déjà sur la carte).

Quoiqu’il en soit, tous les éléments partagent un comportement commun : ils sont sur la carte. Du coup, Props et Buildings dérivent tous deux de Objects, qui décrit le comportement d’un “objet” sur la carte.

Mais il y a aussi différents types de Buildings, notamment :

les Markets qui sont les bâtiments qui vont refléter l’état de la boutique du joueur
les Productions qui sont les bâtiments qui vont permettre de transformer une ressource (raisin, jus) en produit (jus, bouteille)

Notre chaîne d’héritage initiale

À propos de la constructibilité

Après avoir discuté avec le Game Designer, on se rend finalement compte que les Markets ne sont pas constructibles : il sont déjà sur la carte de base.

La constructibilité est un comportement qui faisait partie intégrante de Buildings à ce stade. Mais soit, on peut se dire qu’on va s’en sortir facilement en changeant la chaîne d’héritage ainsi :

Notre chaîne d’héritage modifiée pour s’adapter

Et là, c’est le drame

Puis le temps passe, les specs évoluent et les features avec : brace yourself, Decorations are coming!

Les Decorations, ce sont des éléments de décor (des Props), sauf qu’ils sont constructibles eux aussi !

Bon, à ce stade on est un peu coincés parce-que Constructables ça hérite de Buildings. On aimerait éviter de dupliquer Constructables pour recoder quasiment la même chose côté Props.

Dans le meilleur des scénarios, on se retrouve donc avec des classes qui héritent de propriétés inutiles.

On n'a pas été très malins et on est coincés !

Why so pseudo-classical?

Alors comment en sommes-nous arrivés là ? Comment s’en sortir ?

En fait, nous nous sommes un peu précipités quand la problématique de la constructibilité est apparue. Sans plus y réfléchir nous avons tenu la logique ”Productions EST un Constructables qui EST un Buildings qui EST un Objects”. Et PAF l’héritage !

Si on y regarde mieux, la constructibilité c’est un comportement. On ne peut pas dire que sans Buildings il n’y a pas d’élément Constructables. C’est une subtilité et une erreur assez fréquente en JavaScript parce-que l’héritage pseudo-classique c’est la seule chose que l’on retient : c’est le premier (mauvais) réflexe.

Dans notre cas, la seule chaîne d’héritage vraiment légitime est peut-être celle qui lie Decorations à Props. Et encore, je dis que l’on peut s’en passer.

En réalité, ce que l’on fourre dans Objects, c’est un ensemble de comportements qui sont communs à Props et Buildings. Mais en pratique, Objects ne représente rien de concret : ce serait une classe abstraite si nous faisions du Java. Idem pour Buildings ici d’ailleurs.

Embrace composition

En JavaScript, je vous suggère de le prendre autrement : décrivons chaque comportement dans un objet qui lui est propre. Laissons tomber les constructeurs et la chaîne d’héritage.

Puis, combinons ces objets pour former le prototype des objets qui nous intéresse. Pas de classe à l’horizon, simplement des objets qui se composent d’autres objets. Éventuellement des factories pour construire le bon objet au besoin.

Il est bien plus simple de jouer aux Legos !

Dans le cas de où l’on vient augmenter notre prototype avec d’autres objets, qui décrivent des comportements, on parle alors de mixin.

Si notre objet hérite d’un autre objet, on préfèrera utiliser l’héritage de prototype.

Et avec Backbone ?

Backbone.extend

Quand on utilise Backbone, on se sert de .extend() pour surcharger Backbone.[Model|Collection|View|…]. Puis on l’instancie avec new.

Du coup, il est assez fréquent de suivre le réflexe de l’héritage pseudo-classique et de se retrouver avec :

var ObjectsModel = Backbone.Model.extend( … );
var BuildingsModel = ObjectsModel.extend( … );
var MarketsModel = BuildingsModel.extend( … );

Ce qui revient d’ailleurs à écrire :

var MarketsModel = Backbone.Model.extend(…).extend(…).extend(…);

// Et on instancie au besoin
var marketsModel = new MarketsModel();

Backbone est ainsi fait et .extend() nous emmène très facilement sur cette pente glissante où les Models dépendent les uns des autres de manière plus ou moins subtile.

Composer son prototype PUIS étendre

Quitte à devoir hériter de Backbone, autant limiter les dégâts. Ce n’est pas parce-que .extend() existe que nous sommes contraints de l’utiliser pour chaque objet que nous créons. Le seul objet que nous ayons à .extend() véritablement ici, c’est Backbone.Model.

L’idée, c’est de composer des objets pour former le prototype que nous allons ensuite utiliser dans le .extend() de notre Model / Collection / Vue…

var objectsModelProto = {
  /* … */
}
var buildingsModelProto = {
  /* … */
}
var constructablesModelProto = {
  /* … */
}

// On compose pour former un nouveau prototype.
var marketsModelProto = _.assign(
  {
    /* … */
  }, // -> interface spécifique à markets
  objectsModelProto, //
  buildingsModelProto, // => nos mixins
  constructablesModelProto, //
  {
    /* … */
  } // -> pour surcharger nos mixins, si besoin
)

// Une fois le prototype créé, on hérite de Backbone.
var MarketsModel = Backbone.Model.extend(marketsModelProto)

// Puis on instancie.
var marketsModel = new MarketsModel()

Ici objectsModelProto, buildingsModelProto et constructablesModelProto viennent surcharger le prototype de base de marketsModelProto pour rajouter des comportements spécifiques.

Merge ou assign

À noter qu’il peut être intéressant d’utiliser _.merge plutôt que _.assign si l’on souhaite pouvoir fusionner les attributs. Ça peut être pratique avec Backbone pour fusionner certains attributs tels que events :

var objectsViewProto = {
  events: {
    'click .store': 'store',
    'click .turn': 'turn',
  },

  store: function store() {
    /* … */
  },
  turn: function turn() {
    /* … */
  },
}

_.assign(
  {
    displayModal: function displayModal() {
      /* … */
    },
    select: function select() {
      /* … */
    },
  },
  objectsViewProto,
  {
    events: {
      click: 'select',
      'click .turn': 'displayModal',
    },
  }
)
// ->
// {
//   events: {
//     "click": "select",
//     "click .turn": "displayModal"
//   },
//
//   displayModal: function displayModal () { /* … */ },
//   select: function select () { /* … */ },
//   store: function store () { /* … */ },
//   turn: function turn () { /* … */ }
// }

_.merge(
  {
    displayModal: function displayModal() {
      /* … */
    },
    select: function select() {
      /* … */
    },
  },
  objectsViewProto,
  {
    events: {
      click: 'select',
      'click .turn': 'displayModal',
    },
  }
)
// ->
// {
//   events: {
//     "click": "select",
//     "click .store": "store",
//     "click .turn": "displayModal"
//   },
//
//   displayModal: function displayModal () { /* … */ },
//   select: function select () { /* … */ },
//   store: function store () { /* … */ },
//   turn: function turn () { /* … */ }
// }

Pour conclure

Préférez la composition d’objets plutôt que l’héritage. N’utilisez l’héritage que si cela fait vraiment sens, ou si c’est nécessaire. Gare aux longues chaînes d’héritage : c’est fragile.

Ce qu’il est préférable d’éviter :

// markets.model.js
var MarketsModel = ConstructablesModel.extend({
  /* … */
})

// main.js
var marketsModel = new MarketsModel()

Plus flexible, plus simple :

// markets.model.js
var marketsModelProto = _.assign(
  {
    /* … */
  }, // -> interface spécifique à markets
  objectsModelProto,
  buildingsModelProto,
  constructablesModelProto
)

// main.js
var MarketsModel = Backbone.Model.extend(marketsModelProto)
var marketsModel = new MarketsModel()

Pour finir, voici quelques articles que je vous recommande pour aller plus loin sur le sujet de la composition et de l’héritage en JavaScript :

Understanding Prototypes, Delegation & Composition > une explication de A à Z simple, claire et illustrée
Common Misconceptions about Inheritance in Javascript > FAQ détaillée qui va au fond de la question

Inheritance, composition and Backbone.js

Fri, 19 Jun 2015 00:00:00 GMT

“Favor objects composition over inheritance”

When you’re doing Object Oriented Programmation (OOP), you create a bunch of objects with their data structure and methods that compose their interface. You decide how to split your objects based on the Single Responsibility Principle (SRP): each object should have one and only one reason to change.

To make interesting stuff happen, you need to combine those objects.

Roughly, there are 2 types of relationships in an object model: inheritance and composition.

You can do the analogy with a family tree:

inheritance is like a birth: when it happens, this is for life.
composition is like a marriage: it happens during the participating objects’ lifetimes, and it can change. Objects can discard partners and get new partners to collaborate with. Please note that objects are surely not monogams.

Source: Object Design - Roles, Responsibilities and Collaborations

“Inheritance” all the things!

The very first thing JavaScript developers do is trying to mimic rules of pseudo-classical inheritance.

They usually quickly come up with a lot of new everywhere and inheritance chains awfully long. That generally produce something very hard to maintain.

That’s true you’ve got everything you need to do inheritance with classes, interfaces, … in Java.

This is not JavaScript.

Keep It Simple, Seriously

The base rule in JavaScript is prototypal inheritance.

Forget about the technical jargon, just remember you have objects that can link to other objects (OLOO).

Thus, it’s way simpler to encapsulate methods from a same logic into an object, then simply return this object. If you need to, you can also create a function that will return an object — which is what we call a factory.

Then you’ll take this object, eventually compose it with others, to build the prototype which you’ll use to instantiate your class. That simple.

To sum it up: instead of creating huge, poorly built, inheritance chains from constructors, simply create your objects and compose them to create a prototype you will instantiate your class with.

Concatenative inheritance

Someone notified me that what I’m talking about here is called multiple inheritance, not actual object composition.

When you do object composition, you make attributes point to instances of other classes.

There is no multiple inheritance in JavaScript. Still, composing different prototypes to produce a totally new one is a very close notion, which can be confusing. Here we are talking about “composing prototypes”, but not in the terms of objects composition…

There you’ll find a more concrete explanation: Composition, Inheritance, and Aggregation in JavaScript

So, let’s call that concatenative inheritance, as detailed by Eric Eliott.

With a concrete example

Context

For quite some time I’ve been working full-time on Vinoga, a social-farming game about wine, developed in HTML5.

Among few libraries, we use Backbone.js to decouple our views from our data with ease.

Let’s take a concrete use case: elements on the map.

If we take a few time to think about it, there are actually 2 types of elements:

Props that are decorations elements — trees, rocks, paths…
Buildings that are buildings of the game — winery, castle…

There is, among others, one difference we can notice from now: Buildings can be constructed — from the build menu —, not Props since they already are on the map.

Whatever, all these elements share a common behavior: they are on the map. Hence, Props and Buildings both inherit from Objects, which describes the behavior of an “object” on the map.

But there also are different types of Buildings, such as:

Markets that are buildings that will reflect the state of the player’s store
Productions buildings, that will transform resources — grape, juice — into another product — juice, bottle.

Our initial inheritance chain

About constructability

After we discussed with the Game Designer, we realized that Markets are not constructable: they already are on the map.

Constructability is a behavior that were part of the Buildings one until now. But yep, let’s handle that with a little modification of the inheritance chain:

Our updated inheritance chain to adapt

Here comes the drama

As time goes, specs evolve and features too: brace yourself, Decorations are coming!

Decorations are decorations elements — actually, Props — except that they are constructables too!

Well, now we’re a bit stucked since ConstructableBuildings inherits from Buildings. We’d like not to duplicate ConstructableBuildings to recode roughly the same thing into Props.

Looks like we’ll end up with classes that inherit of useless properties at the very best.

We weren't very smart on this one, now we're stuck!

Why so pseudo-classical?

Well, how did we get there? How to get out of here?

Actually, we were a bit in the hurry when the constructability question appears. Without any more reflexion we came with the logic that ”Productions IS a ConstructableBuildings that IS a Buildings that IS an Objects”. Kaboom, inheritance!

In fact, if we look closer, we could infer that constructability is a behavior. You can not say that there is no Constructable element without Building. This is a subtle error that is so frequent in JavaScript because of pseudo-classical inheritance since this is the only thing you remember: this is the very first — bad — instinct.

In our case, the only legitimate inheritance chain may be the one that bounds Decorations to Props. Anyway, I still think that you can get rid of it too.

What you actually put into Objects is a bunch of behaviors that are shared between Props and Buildings. But technically, Objects doesn’t represent anything concrete: this would be an abstract class if we were coding in Java. Just like Buildings by the way.

Embrace composition

In JavaScript, may I suggest another way: let’s describe each behavior into its own object. Let’s get rid of constructors and inheritance chains.

Then, combine these objects to make the prototype of objects we want to build. No class around, simply objects that are composed from other objects. Eventually factories to construct the correct object regarding your needs.

It's way simpler to play Legos!

Here we just augment our prototype with other objects that describe behaviors. That’s what mixin is about.

If your object inherits from another, then prefer to use prototypal inheritance.

What about Backbone?

Backbone.extend

When you use Backbone, you use .extend() to override Backbone.[Model|Collection|View|…]. Then you instantiate it with new.

Thus, it’s very frequent to follow the pseudo-classical inheritance reflex and to end up with:

var ObjectsModel = Backbone.Model.extend( … );
var BuildingsModel = ObjectsModel.extend( … );
var MarketsModel = BuildingsModel.extend( … );

Which, by the way, would be the same than:

var MarketsModel = Backbone.Model.extend(…).extend(…).extend(…);

// Then you instantiate when needed
var marketsModel = new MarketsModel();

Backbone is built like that. .extend() easily lead us to that slippery slope where Models depend on the others in many not-that-subtle ways.

Compose your prototype THEN extend

Even though you need to inherit from Backbone, you can at least limit the damages. Even though .extend() exists, you don’t have to use it for every single object you create. The only object we really need to .extend() here is Backbone.Model.

The main idea is to compose objects to make to prototype you will then use into the .extend() of your Model / Collection / View…

var objectsModelProto = {
  /* … */
}
var buildingsModelProto = {
  /* … */
}
var constructablesModelProto = {
  /* … */
}

// We compose to make a new prototype.
var marketsModelProto = _.assign(
  {
    /* … */
  }, // -> specific interface for markets
  objectsModelProto, //
  buildingsModelProto, // => our mixins
  constructablesModelProto, //
  {
    /* … */
  } // -> to override mixins, if needed
)

// Once prototype is created, inherit from Backbone.
var MarketsModel = Backbone.Model.extend(marketsModelProto)

// Then you instantiate.
var marketsModel = new MarketsModel()

You can see how objectsModelProto, buildingsModelProto and constructablesModelProto override the base prototype of marketsModelProto to add specific behaviors.

Merge or assign

Please note that might be useful to use _.merge instead of _.assign if you need to merge attributes deeply. This may be handy with Backbone when you need to merge things like events:

var objectsViewProto = {
  events: {
    'click .store': 'store',
    'click .turn': 'turn',
  },

  store: function store() {
    /* … */
  },
  turn: function turn() {
    /* … */
  },
}

_.assign(
  {
    displayModal: function displayModal() {
      /* … */
    },
    select: function select() {
      /* … */
    },
  },
  objectsViewProto,
  {
    events: {
      click: 'select',
      'click .turn': 'displayModal',
    },
  }
)
// ->
// {
//   events: {
//     "click": "select",
//     "click .turn": "displayModal"
//   },
//
//   displayModal: function displayModal () { /* … */ },
//   select: function select () { /* … */ },
//   store: function store () { /* … */ },
//   turn: function turn () { /* … */ }
// }

_.merge(
  {
    displayModal: function displayModal() {
      /* … */
    },
    select: function select() {
      /* … */
    },
  },
  objectsViewProto,
  {
    events: {
      click: 'select',
      'click .turn': 'displayModal',
    },
  }
)
// ->
// {
//   events: {
//     "click": "select",
//     "click .store": "store",
//     "click .turn": "displayModal"
//   },
//
//   displayModal: function displayModal () { /* … */ },
//   select: function select () { /* … */ },
//   store: function store () { /* … */ },
//   turn: function turn () { /* … */ }
// }

In conclusion

Favor objects composition over inheritance. Don’t use inheritance if it doesn’t really make sense, or is required. Beware overlong inheritance chains: that’s damn fragile.

What is preferable to avoid:

// markets.model.js
var MarketsModel = ConstructablesModel.extend({
  /* … */
})

// main.js
var marketsModel = new MarketsModel()

Far more flexible, simpler:

// markets.model.js
var marketsModelProto = _.assign(
  {
    /* … */
  }, // -> specific interface of markets
  objectsModelProto,
  buildingsModelProto,
  constructablesModelProto
)

// main.js
var MarketsModel = Backbone.Model.extend(marketsModelProto)
var marketsModel = new MarketsModel()

Let’s end up this post with few post I recommend you to read if you need to know more about composition and inheritance with JavaScript:

Understanding Prototypes, Delegation & Composition > an explanation from A to Z which is simple, clear and illustrated
Common Misconceptions about Inheritance in Javascript > detailed FAQ that goes deep on this subject

Fonctions pures en JavaScript

Sun, 25 Jan 2015 00:00:00 GMT

C’est quoi ça une fonction “pure” ?

Une fonction pure ne dépend pas et ne modifie pas l’état de variables hors de sa portée.

En pratique, cela signifie qu’une fonction pure retourne toujours le même résultat avec des paramètres identiques. Son exécution ne dépend pas de l’état du système.

Les fonctions pures sont d’ailleurs un pilier de la programmation fonctionnelle.

Quelques exemples

var values = { a: 1 }

function impureFunction(items) {
  var b = 1

  items.a = items.a * b + 2
}

var c = impureFunction(values)
// Désormais `values.a` vaut 3 car la fonction impure l'a modifié.

Ici, on modifie les attributs de l’objet passé en paramètre, donc on modifie l’objet en dehors de la portée de notre fonction également : elle est impure dans ce cas.

var values = { a: 1 }

function pureFunction(a) {
  var b = 1

  a = a * b + 2

  return a
}

var c = pureFunction(values.a)
// `values.a` n'a pas été modifié, c'est toujours 1

Ici, on modifie simplement le paramètre dans la portée de la fonction, on ne touche à rien d’autre en dehors !

var values = { a: 1 }
var b = 1

function impureFunction(a) {
  a = a * b + 2

  return a
}

var c = impureFunction(values.a)
// En fait la valeur de `c` dépend de celle de `b`.
// Dans une base de code plus grande vous risquez d'oublier ce
// détail et le résultat peut vous surprendre car il peut varier
// de manière implicite.

La variable b n’est pas dans la portée de la fonction. Le résultat dépendra du contexte : surprises garanties !

var values = { a: 1 }
var b = 1

function pureFunction(a, c) {
  a = a * c + 2

  return a
}

var c = pureFunction(values.a, b)
// Ici il est clair que la valeur de `c` dépend de celle de `b`.
// Pas de surprise en douce.

Et en pratique ça donne quoi ?

Considérons que ce code existe :

var getMinQuantity = function getMinQuantity(name) {
  // Une fonction pure qui retourne une valeur numérique
  // en fonction du name.
}

Et prenons donc l’exemple du code suivant que l’on pourrait retrouver dans un projet lambda :

var popover = {
  // Un tas de code…

  addQuantityText: function(quantity) {
    var quantityTextOptions = {
      namespace: 'quantity',
      initialChildIndex: 2,
      quantity: quantity,
    }

    try {
      this.formatQuantityText(quantityTextOptions)
    } catch (err) {
      console.log("Couldn't add quantity text!")
    }
  },

  formatQuantityText: function(options) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0
    var initialChildIndex = options.initialChildIndex || 0

    var $$quantity = new Canvas() // implementation details hidden
    $$quantity.name = namespace
    $$quantity.value = quantity
    this.setQuantityTextColor($$quantity)

    this.$$boxContainer.addChild($$quantity, initialChildIndex)

    return $$quantity
  },

  setQuantityTextColor: function($$quantity) {
    if (!$$quantity) return

    var minQuantity = getMinQuantity($$quantity.name)
    var quantity = $$quantity.value || minQuantity
    var hasEnoughQuantity = quantity >= minQuantity

    $$quantity.color = hasEnoughQuantity ? 'green' : 'red'
  },

  // Un tas de code…
}

Ici nous avons addQuantityText(), formatQuantityText() et setQuantityTextColor() qui sont toutes impures.

Dans notre contexte, c’est addQuantityText() qui est utilisée lorsque l’on souhaite “afficher la quantité” dans notre $$boxContainer. C’est le point d’entrée qui se charge de tous les détails. C’est dans cette fonction qu’on va aller jeter un œil si un soucis se présente avec notre $$quantity. Ça risque de devenir un vrai jeu de piste.

La manière dont il a été écrit peut être propice à certaines erreurs sur le long terme.

Quand ça devient compliqué

Dans l’exemple, l’ordre d’exécution des fonctions est garant du bon fonctionnement du code.

Il suffit d’échanger l’ordre de 2 lignes pour tout casser. Ça peut paraître évident, mais ça l’est beaucoup moins à repérer :

var popover = {
  // Un tas de code…

  addQuantityText: function(quantity) {
    var quantityTextOptions = {
      namespace: 'quantity',
      initialChildIndex: 2,
      quantity: quantity,
    }

    try {
      this.formatQuantityText(quantityTextOptions)
    } catch (err) {
      console.log("Couldn't add quantity text!")
    }
  },

  formatQuantityText: function(options) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0
    var initialChildIndex = options.initialChildIndex || 0

    var $$quantity = new Canvas() // implementation details hidden
    this.setQuantityTextColor($$quantity)
    $$quantity.name = namespace
    $$quantity.value = quantity

    return $$quantity
  },

  setQuantityTextColor: function($$quantity) {
    if (!$$quantity) return

    var minQuantity = getMinQuantity($$quantity.name)
    var quantity = $$quantity.value || minQuantity
    var hasEnoughQuantity = quantity >= minQuantity

    $$quantity.color = hasEnoughQuantity ? 'green' : 'red'
  },

  // Un tas de code…
}

Il y a désormais une erreur dans le code. Le problème, c’est que ça ne saute pas aux yeux !

Ici, setQuantityTextColor() est responsable de la couleur de $$quantity. Du coup, il faut naviguer de méthodes en méthodes pour trouver celle qui modifie l’objet en dernier et reconstituer le flow pour comprendre ce qui pourrait mal se passer.

À ce moment là, on pourrait presque s’en mordre les doigts d’avoir découpé formatQuantityText() en petites méthodes pour simplifier les détails de son implémentation.

D’une manière générale d’ailleurs, ça fait pas mal de code à considérer en cas de debug. Et si on commence à estimer que décomposer une grosse méthode en petites complique la tâche de debug, alors le concept de fonction pure prend de l’intérêt.

Avec des fonctions pures

Reprenons notre code en utilisant cette fois un maximum de fonctions pures :

var popover = {
  // Un tas de code…

  // L'ensemble des modifications de l'état du système sont
  // concentrées ici.
  // Seule cette méthode est responsable de l'insertion
  // d'un élément, ce qui simplifie le debug et limite les
  // effets de bord.
  addQuantityText: function(quantity) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var quantityTextOptions = {
      namespace: 'quantity',
      quantity: quantity,
    }
    var $$quantity = this.formatQuantityText(quantityTextOptions)

    this.$$boxContainer.addChild($$quantity, 2)
  },

  // Cette fonction n'a pas d'effet de bord.
  // Elle n'appelle que des fonctions pures. Elle crée et
  // retourne l'objet canvas désiré, correctement configuré !
  formatQuantityText: function(options) {
    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0

    var $$quantity = new Canvas() // implementation details hidden
    $$quantity.name = namespace
    $$quantity.value = quantity
    $$quantity.color = this.getQuantityTextColor(quantity, namespace)

    return $$quantity
  },

  // Cette méthode n'a plus d'effet de bord non plus,
  // elle se charge de renvoyer la bonne couleur en fonction
  // de la quantité en paramètre.
  getQuantityTextColor: function(quantity, namespace) {
    var minQuantity = getMinQuantity(namespace)
    var hasEnoughQuantity = quantity && quantity >= minQuantity

    return hasEnoughQuantity ? 'green' : 'red'
  },

  // Un tas de code…
}

Il n’y a pas de changement fondamental dans cette nouvelle version du code. Et pourtant, les bénéfices ne sont pas négligeables.

Ce qu’on a fait :

getQuantityTextColor() plutôt que setQuantityTextColor()
la méthode nous retourne une couleur en fonction de la quantité passée en paramètre au lieu de modifier l’objet qu’on lui passait en paramètre auparavant
les méthodes ne dépendent plus de variables en dehors de leur portée
les méthodes appellent uniquement des méthodes pures
on isole la création / modification de l’objet $$quantity dans formatQuantityText()
on isole les modifications de l’état du système dans la seule méthode addQuantityText()

Ainsi, nous avons supprimé les méthodes qui avaient des effets de bords. Nous avons donc simplifié la maintenance du code. Si jamais il y a un soucis avec $$quantity, il n’y a qu’une méthode à regarder.

Simplification de l’interface

Nous utilisons ici des méthodes publiques. Il serait tout à fait envisageable, voire carrément pertinent, de les rendre privées.

En effet, elles n’ont pas grand chose à faire dans notre API car leur rôle est de simplifier l’interface. Allez jeter un œil à mon article sur les fonctions privées avec Backbone.js si ça vous laisse perplexe.

Comme elles sont pures, les extraire est un jeu d’enfant puisqu’elles ne dépendent d’aucun contexte mais simplement des paramètres !

function getQuantityTextColor(quantity, namespace) {
  var minQuantity = getMinQuantity(namespace)
  var hasEnoughQuantity = quantity && quantity >= minQuantity

  return hasEnoughQuantity ? 'green' : 'red'
}

function formatQuantityText(options) {
  var namespace = options.namespace || 'quantity'
  var quantity = options.quantity || 0

  var $$quantity = new Canvas() // implementation details hidden
  $$quantity.name = namespace
  $$quantity.value = quantity
  $$quantity.color = getQuantityTextColor(quantity, namespace)

  return $$quantity
}

Et du coup, plus loin dans le code :

var popover = {
  // Un tas de code…

  addQuantityText: function(quantity) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var quantityTextOptions = {
      namespace: 'quantity',
      quantity: quantity,
    }
    var $$quantity = formatQuantityText(quantityTextOptions)

    this.$$boxContainer.addChild($$quantity, 2)
  },

  // Un tas de code…
}

L’intérêt des fonctions pures

L’avantage d’une fonction pure, c’est qu’elle n’a pas d’effets de bord. Elles ne modifient pas l’état du système en dehors de leur portée. Ainsi, elles simplifient et clarifient le code : quand on appelle une fonction pure, on peut se concentrer sur la valeur qu’elle retourne puisqu’on sait qu’elle ne va pas impacter le système en passant.

Une fonction pure est également robuste. Son ordre d’exécution n’a pas d’impact sur le système. Les opérations sur des fonctions pures sont donc parallélisables.

De même, il est très simple de tester une fonction pure puisqu’il n’y a pas de contexte considérer. Il suffit de se concentrer sur les entrées / sorties.

Enfin, maximiser le nombre de fonctions pures rend le code plus simple, plus flexible.

Une question de design

En pratique quand on fait de l’orienté-objet, on se dit que les concepts de la programmation fonctionnelle paraissent inadaptés. C’est une erreur car POO et FP sont parfaitement compatibles !

En effet, l’idée ici est toute simple : simplifier le code en limitant le nombre de fonctions qui ont un impact sur l’état du système.

En s’efforçant à écrire un maximum de fonctions pures, en limitant le nombre de fonctions qui ne le sont pas, on se simplifie la vie !

En tout cas, c’est l’idée. Et souvent, en pratique, c’est surtout une question de design, de choix entre un get et un set par exemple.

Pure functions in JavaScript

Sun, 25 Jan 2015 00:00:00 GMT

What’s that a “pure” function?

A pure function doesn’t depend on and doesn’t modify the states of variables out of its scope.

Concretely, that means a pure function always returns the same result given same parameters. Its execution doesn’t depend on the state of the system.

Pure functions are a pillar of functional programming.

Give me examples

var values = { a: 1 }

function impureFunction(items) {
  var b = 1

  items.a = items.a * b + 2

  return items.a
}

var c = impureFunction(values)
// Now `values.a` is 3, the impure function modifies it.

Here we modify the attributes of the given object. Hence we modify the object which lies outside of the scope of our function: the function is impure.

var values = { a: 1 }

function pureFunction(a) {
  var b = 1

  a = a * b + 2

  return a
}

var c = pureFunction(values.a)
// `values.a` has not been modified, it's still 1

Now we simply modify the parameter which is in the scope of the function, nothing is modified outside!

var values = { a: 1 }
var b = 1

function impureFunction(a) {
  a = a * b + 2

  return a
}

var c = impureFunction(values.a)
// Actually, the value of `c` will depend on the value of `b`.
// In a bigger codebase, you may forget about that, which may
// surprise you because the result can vary implicitly.

Here, b is not in the scope of the function. The result will depend on the context: surprises expected!

var values = { a: 1 }
var b = 1

function pureFunction(a, c) {
  a = a * c + 2

  return a
}

var c = pureFunction(values.a, b)
// Here it's made clear that the value of `c` will depend on
// the value of `b`. No sneaky surprise behind your back.

What does it look like, concretely?

Considering this code exists:

var getMinQuantity = function getMinQuantity(name) {
  // A pure fonction which returns a number, regarding
  // the given name.
}

Let’s take the following code example that may exist in a lambda project:

var popover = {
  // A bunch of code…

  addQuantityText: function(quantity) {
    var quantityTextOptions = {
      namespace: 'quantity',
      initialChildIndex: 2,
      quantity: quantity,
    }

    try {
      this.formatQuantityText(quantityTextOptions)
    } catch (err) {
      console.log("Couldn't add quantity text!")
    }
  },

  formatQuantityText: function(options) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0
    var initialChildIndex = options.initialChildIndex || 0

    var $$quantity = new Canvas() // implementation details hidden
    $$quantity.name = namespace
    $$quantity.value = quantity
    this.setQuantityTextColor($$quantity)

    this.$$boxContainer.addChild($$quantity, initialChildIndex)

    return $$quantity
  },

  setQuantityTextColor: function($$quantity) {
    if (!$$quantity) return

    var minQuantity = getMinQuantity($$quantity.name)
    var quantity = $$quantity.value || minQuantity
    var hasEnoughQuantity = quantity >= minQuantity

    $$quantity.color = hasEnoughQuantity ? 'green' : 'red'
  },

  // A bunch of code…
}

We’ve got addQuantityText(), formatQuantityText() and setQuantityTextColor() which are all impure.

In our context, addQuantityText() is the method actually used when you want to “display the quantity” in our $$boxContainer. This is the entry point, dealing with implementation details. You’ll look at this method when something goes wrong with $$quantity. Which is likely to be the start of a treasure hunt — but not a funny one.

The way it was written could be error-prone on the long term.

When it gets complicated

In this example, the execution order of functions is critical.

Just swap 2 lines and you’ll break everything. It may sound obvious, but it’s much more difficult to debug:

var popover = {
  // A bunch of code…

  addQuantityText: function(quantity) {
    var quantityTextOptions = {
      namespace: 'quantity',
      initialChildIndex: 2,
      quantity: quantity,
    }

    try {
      this.formatQuantityText(quantityTextOptions)
    } catch (err) {
      console.log("Couldn't add quantity text!")
    }
  },

  formatQuantityText: function(options) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0
    var initialChildIndex = options.initialChildIndex || 0

    var $$quantity = new Canvas() // implementation details hidden
    this.setQuantityTextColor($$quantity)
    $$quantity.name = namespace
    $$quantity.value = quantity

    return $$quantity
  },

  setQuantityTextColor: function($$quantity) {
    if (!$$quantity) return

    var minQuantity = getMinQuantity($$quantity.name)
    var quantity = $$quantity.value || minQuantity
    var hasEnoughQuantity = quantity >= minQuantity

    $$quantity.color = hasEnoughQuantity ? 'green' : 'red'
  },

  // A bunch of code…
}

Now there is an error in the code. Problem is: that’s hard stuff to detect!

Here, setQuantityTextColor() is responsible of the color of $$quantity. And so you need to navigate through methods to catch the one which is the last which modifies the object, then reconstitute the whole flow to understand what’s going wrong.

At this point you could even regret having decomposed formatQuantityText() into smaller methods to simplify implementation details.

Generally speaking, that’s a lot of code that needs to be considered when you are debugging. And if you get thinking that splitting a big method into smaller ones just make the debug difficult, then the concept of pure function is gaining interest.

Let’s do that with pure functions

We’ll use a maximum of pure functions to rewrite our code:

var popover = {
  // A bunch of code…

  // All the modifications of system state are grouped here.
  // This only method is responsible for the insertion of
  // an element, which makes debug simpler and limit
  // side effects.
  addQuantityText: function(quantity) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var quantityTextOptions = {
      namespace: 'quantity',
      quantity: quantity,
    }
    var $$quantity = this.formatQuantityText(quantityTextOptions)

    this.$$boxContainer.addChild($$quantity, 2)
  },

  // This method doesn't have side effects.
  // It just call other pure functions. It creates and return the
  // canvas object desired, correctly configured!
  formatQuantityText: function(options) {
    var namespace = options.namespace || 'quantity'
    var quantity = options.quantity || 0

    var $$quantity = new Canvas() // implementation details hidden
    $$quantity.name = namespace
    $$quantity.value = quantity
    $$quantity.color = this.getQuantityTextColor(quantity, namespace)

    return $$quantity
  },

  // This method doesn't have side effects neither.
  // It returns the correct color, regarding the given quantity.
  getQuantityTextColor: function(quantity, namespace) {
    var minQuantity = getMinQuantity(namespace)
    var hasEnoughQuantity = quantity && quantity >= minQuantity

    return hasEnoughQuantity ? 'green' : 'red'
  },

  // A bunch of code…
}

There is no fundamental change in this new version. However, there are non-negligible benefits.

What we did here:

getQuantityTextColor() instead of setQuantityTextColor()
the method returns a color regarding the quantity we give to it instead of modifying the object directly, as we did before
methods don’t consider variables out of their scope
methods only call pure methods
we isolated the creation / modification of the $$quantity object in formatQuantityText()
we isolated modifications of the system state in addQuantityText()

Doing so, we removed methods with side effects. We just simplified the code maintenance. If there is an issue with $$quantity to occur, there is only one method to look for.

Simplify the interface

We used here public methods. It’d be perfectly acceptable — completely relevant — to make them private.

Indeed, there don’t have much to do with our API since their role is to simplify the interface. Have a look to my post on private methods with Backbone.js if you get scratching your head with that.

As they are pures, to extract them is dead easy since they don’t rely on a specific context, just parameters!

function getQuantityTextColor(quantity, namespace) {
  var minQuantity = getMinQuantity(namespace)
  var hasEnoughQuantity = quantity && quantity >= minQuantity

  return hasEnoughQuantity ? 'green' : 'red'
}

function formatQuantityText(options) {
  var namespace = options.namespace || 'quantity'
  var quantity = options.quantity || 0

  var $$quantity = new Canvas() // implementation details hidden
  $$quantity.name = namespace
  $$quantity.value = quantity
  $$quantity.color = getQuantityTextColor(quantity, namespace)

  return $$quantity
}

And then, later in the code:

var popover = {
  // A bunch of code…

  addQuantityText: function(quantity) {
    if (!this.$$boxContainer) {
      throw new Error('$$boxContainer is not configured')
    }

    var quantityTextOptions = {
      namespace: 'quantity',
      quantity: quantity,
    }
    var $$quantity = formatQuantityText(quantityTextOptions)

    this.$$boxContainer.addChild($$quantity, 2)
  },

  // A bunch of code…
}

Advantages of pure functions

The main advantage of a pure function is that it doesn’t have any side effect. It doesn’t modify the state of the system outside of their scope. Then, they just simplify and clarify the code: when you call a pure function, you just need to focus on the return value as you know you didn’t broke anything elsewhere doing so.

A pure function is also robust. Its order of execution doesn’t have any impact on the system. Operations with pure functions could be parallelized.

Also, it’s very easy to unit test a pure function since there is no context to consider. Just focus on inputs / outputs.

Finally, maximizing the use of pure functions makes your code simpler, more flexible.

A matter of design

In practice, when you are doing object-oriented code you may think that functional programming concepts couldn’t fit in. This is simply wrong as OOP and FP are absolutely compatibles!

Indeed, the idea here is simple: simplify your code by limiting the number of functions that has an impact on the system.

If you force yourself to think twice to maximize the number of pure functions in your code, you’ll probably make your maintenance / life / debug easier!

Well, you’ve got the idea. Which is often, in practice, a matter of design, the choice between a get and a set for instance.

POO - le switch revisité en JavaScript

Wed, 14 Jan 2015 00:00:00 GMT

Supposons que les méthodes suivantes existent :

function sayHello() {
  console.log('Hello, how are you?')
}

function giveSomeNews() {
  console.log('Roses are red. Did you know that?')
}

function sayBye() {
  console.log('Ok bye!')
}

Quelques rappels sur le `switch`

if / else permet d’introduire de la logique dans notre code en créant des branches : en fonction d’une condition, nous exécuterons telle ou telle opération. Mais parfois, il y a plus de 2 branches possibles.

Le réflexe initial consiste donc à ajouter des branches avec else if :

if (name === 'patrick') {
  sayHello()
} else if (name === 'jane') {
  giveSomeNews()
} else {
  sayBye() // don't talk to strangers!
}

Comme c’est un petit peu verbeux, peu lisible et encore moins élégant, on utilise alors le switch :

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

switch est une alternative classique à un enchaînement de else if.

À moins qu’il s’agisse d’opérations très petites (quelques lignes, claires et explicites), je préfère les encapsuler dans des fonctions explicitement nommées pour décomposer la logique de l’implémentation. Le switch, c’est la logique. J’utilise la même technique pour les if / else.

La syntaxe est plus claire, mais on introduit certaines subtilités.

Notamment, il faut prendre garde au concept du break introduit ici : il permet de sortir du switch et éviter de passer au case suivant.

Rappel des erreurs à éviter !

Lorsque l’on arrive sur un switch, on s’attend rarement (jamais ?) à passer à travers 2 cas différents.

À l’instar du else if, on s’attend à exécuter un cas et un seul. Pour cette raison, on veille à ne pas oublier le break !

Par exemple, ce code est-il intentionnel ? Est-ce un oubli ? En tout cas, c’est une source de confusion et de bugs !

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
    giveSomeNews()

  default:
    sayBye() // don't talk to strangers!
    break
}

Il existe un cas de figure où, à la limite, l’intention reste claire et qui est acceptable (et utilisée).

Il s’agit de regrouper différents inputs dans un même case :

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
  case 'john':
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

Bref, ne pas mettre un break à chaque case est très souvent propice aux erreurs car le code écrit comporte “une subtilité”, il a donc des chances d’être mal lu / interprété.

Le jeu n’en vaut pas la chandelle, aussi je vous conseille plutôt de ne pas le faire. Après, c’est vous qui voyez mais y’en a qu’on essayé…

Une alternative orientée objet : method lookup

Reprenons à présent notre exemple avec un esprit moins procédural, plus orienté-objet :

var greetings = {
  patrick: sayHello,
  john: giveSomeNews,
  jane: giveSomeNews,
}

typeof greetings[name] === 'function' ? greetings[name]() : sayBye()

On peut appeler cela le method lookup qui traduit finalement l’idée du Command Pattern.

On utilise ici la syntaxe objet naturelle de JavaScript et la puissance de ses fonctions. Pas de break dont on doit se préoccuper. On dispose également de tous les avantages de l’objet, notamment le fait de pouvoir le surcharger facilement et ainsi dépendre d’un contexte particulier.

En pratique, le method lookup est pertinent par rapport au switch si vous vous trouvez dans l’un des cas suivants :

aurez-vous besoin d’ajouter plus de cas ? Par exemple dans le cas de plugins
est-il utile de pouvoir modifier les cas en cours d’exécution ? Par exemple pour changer d’options en fonction du contexte.
est-il utile de log les cas qui ont été exécutés ? Par exemple pour mettre en place un stack de undo / redo, ou un système de log.
êtes-vous en train d’utiliser des nombres pour lister vos cas, de manière itérative ? Par exemple case 1:, case 2:, etc.
êtes-vous en train d’essayer de regrouper des cas ensembles en omettant de manière intentionnelle des break ? Fall through = danger, le method lookup est bien plus clair.

Remarques sur une version du `switch` “avancé”

Avec switch il est possible de tester directement une condition dans le case.

Ainsi, en considérant que ceci existe :

function isPatrick(name) {
  return name === 'patrick'
}

function isJane(name) {
  return /^jane-/.test(name)
}

Le code suivant fonctionne parfaitement :

switch (true) {
  case isPatrick(name):
    sayHello()
    break

  case isJane(name):
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

Pour plus de lisibilité, j’ai effectivement exporté les case dans des fonctions qui expriment clairement l’intention afin de produire un code clair avec cette syntaxe.

Vous conviendrez que la logique est à présent un poil plus complexe. Dans ce cas, il est donc judicieux de travailler à rendre le code plus clair.

Ceci fonctionne, peut se révéler utile et n’a pas d’équivalent avec la method lookup (que je sache).

Cela étant, prenez garde aux abus de logique. Ce n’est pas parce-qu’on peut le faire, qu’on doit le faire. Veillez à garder un esprit critique sur ce que vous faîtes : est-ce vraiment nécessaire ou existe-t-il un moyen plus simple ? Peut-on trouver design plus clair pour exprimer cette logique ?

Parfois on s’emporte dans des trucs “sexy”, mais un bon KISS ne fait jamais de mal !

Release the (object-oriented) Kraken!

Le method lookup / command pattern est l’équivalent du switch dans un esprit objet. Il tend à encourager l’écriture d’un code flexible, bien organisé, orienté-objet (et ça, c’est bien !).

Si switch … case n’est pas mauvais en soi, il peut s’avérer propice aux erreurs et encourage en soi le spaghetti code. Par sa nature procédurale, il peut conduire à une logique de branche complexe qui résulte souvent dans un mauvais design et donc un code peu difficile à maintenir.

En fait, il n’y a pas vraiment de raison d’utiliser switch plutôt que son alternative quand on veut profiter de ce que JavaScript offre. Le principal, c’est de produire un code clair pour votre future-vous et les autres !

OOP - switch revisited in JavaScript

Wed, 14 Jan 2015 00:00:00 GMT

Suppose following methods for the rest of the post:

function sayHello() {
  console.log('Hello, how are you?')
}

function giveSomeNews() {
  console.log('Roses are red. Did you know that?')
}

function sayBye() {
  console.log('Ok bye!')
}

Few reminders about `switch`

if / else allow us to add some branching logic in our code: regarding a condition we’ll do this or that operation. But there are sometimes more than 2 possibles branches.

As a beginner developer, you might be starting using else if:

if (name === 'patrick') {
  sayHello()
} else if (name === 'jane') {
  giveSomeNews()
} else {
  sayBye() // don't talk to strangers!
}

Well, that’s a bit verbose, difficult to read and not that pretty. Here comes switch:

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

switch is the classical alternative to a long chain of else if.

Excepted for very short operations — few lines with clear intent — I prefer to encapsulate them in explicitly named functions to decompose the logic from the implementation details. The logic lies in the switch. I use the same technique for if / else.

Syntax is clearer, but you’re introducing few subtleties.

Most of all, you should be aware of the break concept here: it allows you to get out of the switch and prevent falling through the next case.

Remember errors to avoid!

When you deal with a switch, you’re not likely to expect falling through 2 different cases.

Just like else if, you probably expect to execute one and only one case. That’s why you must take care not to forget the break!

Have a look at this code, is it intentional? Is it a mistake? Whatever, that’s a source of bugs and confusion!

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
    giveSomeNews()

  default:
    sayBye() // don't talk to strangers!
    break
}

There might exists a use case however, where the intent is clear and which is acceptable — and used.

That’s when you want to regroup multiple inputs into the same case:

switch (name) {
  case 'patrick':
    sayHello()
    break

  case 'jane':
  case 'john':
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

To keep it short: to omit a break for each case is error-prone because you’re introducing obscure subtleties in your code. And your code is likely to get future developers into troubles.

That’s why the wise advice is: avoid doing that, do remember the break.

An object-oriented alternative: method lookup

Let’s go back to our example with a less procedural spirit. Let’s get object-oriented:

var greetings = {
  patrick: sayHello,
  john: giveSomeNews,
  jane: giveSomeNews,
}

typeof greetings[name] === 'function' ? greetings[name]() : sayBye()

You can call that the method lookup, which reflect the idea behind the Command Pattern.

We use the natural object syntax of JavaScript and the power of its first-class functions. No break to deal with. We already get all the advantages of the object, as the capability to extend it with ease, allowing context-relative options.

The method lookup is much more relevant than the switch if you’re in one of the following cases:

will you need to add more cases later? Dealing with plugins for instance.
is it useful to change cases during run-time? Like changing options regarding the context.
is it useful to log executed cases? To set up an undo / redo stack, a log system, etc.
are you using incremental numbers to list your cases iteratively? If you use case 1:, case 2:, etc.
are you trying to fall through different cases by intentionally omitting some break? Fall through = danger, method lookup is a much better alternative.

Few remarks on an “advanced” version of `switch`

Using switch, you can directly test a condition in your case.

Doing so, and considering this code exist:

function isPatrick(name) {
  return name === 'patrick'
}

function isJane(name) {
  return /^jane-/.test(name)
}

Then, the following code will perfectly work:

switch (true) {
  case isPatrick(name):
    sayHello()
    break

  case isJane(name):
    giveSomeNews()
    break

  default:
    sayBye() // don't talk to strangers!
    break
}

Again, for more readability I exported conditions into functions that make the intent clear and produce a better code.

You’ll agree that the logic is now a bit more complex. In such a context, it might be relevant to polish your work to make your code clear.

This works and could be very useful. Plus, it doesn’t have any equivalent with the method lookup as far as I know.

However, beware overlogic abuse in your code. The fact you can do it doesn’t imply that you should. Keep a critical mind over what you’re doing: is it really necessary or is there another simpler way? Can I work on a clearer design to express the logic intent?

Sometimes you might go crazy into “sexy” stuff, but nothing values most than KISS!

Release the (object-oriented) Kraken!

The method lookup / command pattern is a switch equivalent, with an object-oriented spirit. It tends to encourage you to write a flexible, well-organized, object-oriented code — which is good.

switch … case is not a bad thing in itself. But it can be lead to spaghetti code and be error-prone. Because its procedural, you may end up with a complex branching logic which finally traduce a bad code design which is difficult to maintain.

Finally, there is no reason to actually use switch instead of its alternative if you want to benefit what JavaScript has to offer. But must of all, the most important is you to write a code the future-you and others won’t hate!

Fonctions privées avec Backbone.js

Sun, 07 Dec 2014 00:00:00 GMT

Fonctions privées, c’est-à-dire ?

Pour faire simple et concis : une fonction / méthode privée est une méthode qui n’est pas exposée et ne peut donc pas être appelée “de l’extérieur”.

Il s’agit donc d’une notion de portée, ni plus ni moins.

function yolo() {
  var privateMethod = function() {
    console.log("can't be accessed outside of `yolo()`")
  }
  var privateVar = true

  // ici, on peut appeler `privateMethod` si ça nous chante.
  // ici, `privateVar` vaut `true`.

  return "that's all you've got from me!"
}

// ici, `privateMethod` n'existe pas.
// ici, `privateVar` n'est pas défini.

yolo() // affiche "that's all you've got from me!"

Cette notion prend tout son sens lorsqu’on utilise le module pattern.

Pour en savoir plus sur ce point, je vous recommande cet article parmi tous les autres : Mastering the module pattern, simple et efficace.

Et donc concrètement, ça donne ce genre de code :

var MyModule = (function() {
  // tout un tas de trucs encapsulés -> privés si pas exposés.
  var _cantTouchThis = function() {
    console.log('I just met you!')
  }

  var _nbOfCats = 3

  // ce que l'on retourne lorsque la fonction est exécutée
  // -> ce qu'on expose (= public).
  return {
    nbOfRainbows: 10,
    sayHi: function() {
      console.log('Hi!')
    },
    logNumberOfRainbows: function() {
      console.log(this.nbOfRainbows)
    },
    logNumberOfCats: function() {
      console.log(_nbOfCats)
    },
    touchThis: function() {
      console.log('Hey!')
      _cantTouchThis()
    },
  }
})()

Ceci nous permet donc de toucher à la partie publique, l’interface, sans pour autant avoir accès à la partie privée :

MyModule.nbOfRainbows = 42
MyModule.logNumberOfRainbows() // affiche "42"
MyModule.logNumberOfCats() // affiche "3"
MyModule.touchThis() // affiche "Hey!" "I just met you!"

Fonctions privées… Et pour quoi faire ?

Question légitime. Personnellement, je vois l’intérêt d’une fonction privée ainsi :

elle simplifie l’interface publique en s’occupant des détails techniques d’implémentation
elle n’a pas à être testée unitairement

Le premier point coule généralement de source. Le second point découle du premier, mais rend souvent perplexe. Je m’explique…

Tests unitaires et fonctions privées

Pour tester notre module, on l’instancie, puis on va prendre chacune de ses méthodes et vérifier leur sortie à partir d’une entrée (variables + contexte). On teste unitairement les méthodes exposées en prenant garde de faire varier l’entrée pour tester tous les cas de figure et obtenir une bonne couverture de tests.

On peut d’ailleurs résumer la pratique du Test Driven Development (TDD) :

écrire d’abord le test avec les cas de figures requis pour une fonctionnalité
coder la méthode afin de passer ces tests
retravailler le code à la fin pour le nettoyer. Tant que les tests passent on sait qu’on n’a rien cassé.

L’étape de refactor vient en dernier car l’objectif est de produire un code qui fonctionne, puis de faire des optimisations.

Pour revenir à la question des méthodes privées : elles ne sont pas exposées, donc techniquement elles ne sont pas testées unitairement. Pas directement en fait.

Quelques considérations sur les fonctions privées

Le point sur les tests unitaires peut laisser perplexe selon la manière dont on considère et utilise la notion de fonction privée. Je dirais qu’il y a 2 façons de voir les choses :

je code tout en privé et j’expose que ce qui doit l’être in fine
les fonctions privées sont le fruit du refactor de mes fonctions publiques

Comment choisir entre privé et public ?

Si on considère que l’on fait du TDD… on développe l’interface publique avant (puisque c’est ce que testent les tests).

Personnellement, je code mes tests (qui ne passent pas), puis mon interface publique : les méthodes publiques ou les event handlers (petit point là-dessus plus bas, pour ceux qui s’interrogent). Rien de privé chez moi à ce stade.

Les fonctions privées proviennent de l’étape de refactor, finalement. Et puis si je n’ai pas le temps de nettoyer, au moins ça marche.

Finalement, les tests unitaires testent l’interface publique.

Les méthodes privées sont testées à travers les méthodes publiques. On peut se dire que tester le détail de l’implémentation technique serait judicieux pour mieux debugguer, mais c’est un coût d’implémentation et de maintenance conséquent. À l’inverse, je peux ici modifier / refactor mes méthodes privées autant que je veux tant que mon module fonctionne.

À choisir : autant tester plus de scénarios sur l’interface publique. La coverage indiquera si oui ou non on teste les méthodes privées en passant.

Le cas des events handlers

L’interface publique, c’est donc ce qui compte.

Qu’en est-il des événements qui font réagir notre module ? Les events handlers (= onClick() & co) doivent-elles être publiques pour pouvoir être testées ?

En fait, non.

On parle d’événements. Notre module écoute des événements et réagit en fonction. Les tests doivent donc déclencher le comportement en émettant les événements, puis en observant le résultat attendu (impact sur le système, etc.). La méthode liée peut bien être publique ou privée, ce n’est pas ce qui compte au moment où l’on teste la manière dont le module répond à l’événement.

Préfixer avec ”_”

Par convention (assez répandue), on préfixe les noms des méthodes / variables privées avec un _.

C’est également ce que je fais pour 2 raisons :

c’est une convention qui présente l’avantage de se démarquer. On n’a pas de private en JS, mais la plupart comprendront qu’on parle là d’une fonction “supposée” privée…
cela facilite le travail de documentation automatique. Souvent, par convention, l’autocompletion considérera cette fonction comme privée et n’oubliera pas de mettre @private. Ça vaut ce que ça vaut, en tout cas ça ne coûte rien \o/

C’est donc personnellement une considération de clarté. La nature privée de la méthode _joke() saute plus facilement aux yeux.

En revanche, il est assez commun que cette convention soit utilisée pour tenter de définir la nature privée d’une méthode au lieu de la mettre en valeur. C’est-à-dire que l’interface publique exposée est composée de méthodes dont certaines sont préfixées avec _ pour indiquer que celles-ci doivent être considérées comme privées.

C’est un point qui génère de nombreux débats. D’après mon expérience personnelle, c’est généralement quelque chose qui est mis en place quand on ne sait pas trop comment on fait pour véritablement mettre en place des méthodes privées. Du coup tout est public, mais on indique que certaines sont privées par intention.

En pratique, il est assez simple de mettre en place des méthodes privées avec le module pattern. Tant qu’à faire, je conseille donc de partir du principe que tout ce qui est exposé est public. Si on souhaite qu’une fonction soit privée, alors autant l’écrire comme telle et utiliser le préfixe _ simplement pour la lisibilité du code.

Cela étant, à chaque projet de définir et suivre ses conventions selon ses besoins.

C’est pas dans le prototype… du coup pour l’héritage et la performance ?

Effectivement, étant donné qu’elle n’est pas accessible, une méthode privée ne peut pas être surchargée. C’est la raison pour laquelle je considère les méthodes privées comme un moyen de simplifier l’interface exposée de mon module. Si j’ai besoin du détail de l’implémentation, que je dois pouvoir y accéder en héritant ma classe, alors j’ai besoin que ce détail soit public.

Là encore, le scepticisme n’est pas tellement causé la nature des méthodes privées en soi, mais plutôt à une interprétation / implémentation maladroite de celles-ci.

On notera également le point sur la performance : il y aura autant de fonctions privées que d’instances de mon module, ce qui est techniquement moins performant. Mais en analysant effectivement l’impact, cette remarque relève de l’ordre de l’optimisation précoce dans mon utilisation des méthodes privées, pour le moment.

Et comment j’accède à mes méthodes publiques depuis mes méthodes privées ?

Ceci peut être un point de blocage.

En fait, si ma fonction privée provient d’un refactor de ma méthode publique, ce n’en est plus un. Tout simplement parce-que ma méthode privée a pour rôle de simplifier l’interface publique, c’est-à-dire de rendre plus lisible ma méthode publique.

J’envisage donc la méthode privée comme un “helper” personnel du module, dont il se sert pour faire son travail. Toutes les variables dont la méthode a besoin lui son donc passées en paramètre.

Ainsi, on peut simplement envisager de passer le contexte de l’interface publique à la méthode privée :

var MyModule = (function() {
  var _addSomeCats = function(context) {
    context.cats++
    context.logNumberOfCats()
  }

  return {
    cats: 1,
    addSomeCats: function() {
      // En soi cela n'a pas grand intérêt ici de tout envoyer
      // dans une méthode privée, mais c'est pour illustrer la
      // manière dont on passe le contexte.
      _addSomeCats(this)
    },
    logNumberOfCats: function() {
      console.log(this.cats)
    },
  }
})()

Ce qui donnera :

MyModule.addSomeCats() // affiche "2"

Dans cet exemple, le contexte est passé en paramètre.

En pratique, il est possible d’utiliser this dans la méthode _addSomeCats et de l’appeller en lui passant le contexte avec .call() ainsi : _addSomeCats.call(this).

L’exemple précédent ne présente pas un grand intérêt, mais concrètement cela peut se présenter de la manière suivante dans un projet :

var MyModule = (function() {
  // syntaxe alternative de `var _createViewInstance = function() { … }`.
  // on a refactor ici quelques tâches répétitives du module.
  function _createViewInstance(View, $parent) {
    if (!View) throw new Error('No View constructor provided')
    if (!$parent) throw new Error('No $parent provided')

    var view = new View()
    view.$el.appendTo($parent)
    view.render()

    return view
  }

  // …

  return {
    onRender: function() {
      try {
        this.ordersView = _createViewInstance(this.OrdersView, $('#orders'))
      } catch (err) {
        app.err(err) // -> notre façon de log les erreurs qui peuvent subvenir
        this.ordersView = {}
      }

      // un tas d'autres trucs…
    },

    // …
  }
})()

Ce qui nous amène effectivement à Backbone.js.

Implémentation avec Backbone.js

C’est le point qui fut pour moi la cause de cet article. En effet, après avoir assimilé le concept et bien visualisé sa mise en place avec un module, on peut rester perplexe sur la manière de l’implémenter quand on à l’habitude de ceci :

var MyModule = (function() {
  var Books = {}

  Books.Model = Backbone.Model.extend({
    // un peu de configuration…

    isPrivate: function() {
      console.log('certainly not…')
      return false
    },

    _intendedToBePrivate: function() {
      // le genre de méthode qui apparaît dans ce genre de situation.
    },
  })

  // …

  return Books
})()

Finalement, le principe est simple : .extend() prend un objet en paramètre. Qu’à cela ne tienne, on peut lui envoyer une IIFE qui lui retourne un objet (son API).

var MyModule = (function() {
  var Books = {}

  var ModelConfiguration = (function() {
    var _actuallyPrivate = function() {
      console.log("look 'ma, I'm private!")
    }

    // on expose la configuration.
    return {
      defaults: {
        isCompleted: false,
      },

      urlRoot: '/order',

      isCompleted: function() {
        _actuallyPrivate()
        return this.get('isCompleted')
      },
    }
  })()

  Books.Model = Backbone.Model.extend(ModelConfiguration)

  // …

  return Books
})()

Pour conclure

La question des fonctions privées et de leur intérêt fait toujours débat et peut laisser sceptique. Parfois (souvent ?), ça complique plus le schmilblick qu’autre chose. Aussi, chaque projet doit trouver midi à sa porte et adopter la position qui lui convient.

En ce qui me concerne, je crée des méthodes privées lors de mes opérations de refactor. Si la méthode est publique par nature, je la traite comme telle : pas de préfixe _, des tests unitaires. Le plus important pour moi, c’est de ne pas me leurrer avec une convention.

Quoiqu’il en soit, je me suis questionné un bon moment pour comprendre comment cela pouvait se traduire en utilisant Backbone.js. Et comme j’ai eu du mal à faire le déclic, je me suis fendu de cet article pour aider les prochains qui entreront dans les mêmes réflexions que j’ai pu avoir.

Cela étant, c’est un point à débats et à réflexions. N’hésitez donc pas, je suis preneur de suggestions et remarques à ce sujet !

Private methods with Backbone.js

Sun, 07 Dec 2014 00:00:00 GMT

Private method, what is that?

To keep it short: a private method is a method which is not exposed and can’t be called “from the outside”.

It’s just a matter of scope after all.

function yolo() {
  var privateMethod = function() {
    console.log("can't be accessed outside of `yolo()`")
  }
  var privateVar = true

  // here, you can call `privateMethod` if you wish to.
  // here, `privateVar` returns `true`.

  return "that's all you've got from me!"
}

// here, `privateMethod` doesn't even exist.
// here, `privateVar` is undefined.

yolo() // returns "that's all you've got from me!"

This notion makes sense with the module pattern.

To learn more on that subject, I’d strongly recommend this post among others: Mastering the module pattern, simple and efficient.

Well, concretely, here’s what you’ve got:

var MyModule = (function() {
  // a bunch of encapsulated stuff -> private if not exposed
  var _cantTouchThis = function() {
    console.log('I just met you!')
  }

  var _nbOfCats = 3

  // what you return when the method is executed
  // -> what you expose (= public).
  return {
    nbOfRainbows: 10,
    sayHi: function() {
      console.log('Hi!')
    },
    logNumberOfRainbows: function() {
      console.log(this.nbOfRainbows)
    },
    logNumberOfCats: function() {
      console.log(_nbOfCats)
    },
    touchThis: function() {
      console.log('Hey!')
      _cantTouchThis()
    },
  }
})()

This allow you to manipulate the public part — the interface — without having access to the private part:

MyModule.nbOfRainbows = 42
MyModule.logNumberOfRainbows() // returns "42"
MyModule.logNumberOfCats() // returns "3"
MyModule.touchThis() // returns "Hey!" "I just met you!"

Private methods… for what?

That’s a legitimate question. I personally found 2 advantages of a private method:

it simplifies the public interface hiding technical details of the implementation
it doesn’t have to be unit tested

The first point is generally obvious. The second one arises from the first point, but may turn you suspicious. Let me explain…

Unit tests and private methods

To test our module, we instantiate it, then take every single method and check the output for a given input (variable + context). We unitly test the exposed method, taking care to make the input vary to test every use case and get a good test coverage.

We can remind the Test Driven Development (TDD) process:

first write the test with required use cases for our functionality
then code the method, pass tests
refactor code to clean the whole thing. As long as tests pass, you didn’t break anything.

The refactor step is the last one because we first want to produce something that works, then focus on optimizations.

Let’s get back to private methods: since they are not exposed, they are not technically unit tested. In fact, not directly.

Some considerations about private methods

The TDD point can leave you suspicious depending on the manner you consider and use the privacy notion. I think there is two ways of doing things:

first code everything as private, then expose what needs to be
private methods came from public methods refactor step

How to choose between private and public?

Considering you’re doing TDD… you develop the public interface first — that’s what you’re testing after all.

Personally, I code my (failing) tests, then my public interface: public methods or event handlers — we’ll talk about that few lines below. Nothing private with my code at this point.

Private methods appears during refactor step, at last. And if I don’t have time for that the code is working, at least.

Finally, unit tests test the public interface.

Private methods are tested through public ones. You may think that testing the detail of technical implementation would be a great idea to ease the debug part, but this would be also a cost to implement and maintain. On the contrary, I can update / refactor private methods as long as my module is still working as expected.

If I have to choose, I’d prefer to invest in testing more use case. The coverage will tell me if I actually test private methods, passing by.

About events handlers

Public interface matters.

What about events that make our module react? Should event handlers (e.g. onClick() & cie.) be public to be tested?

Well, no.

We’re talking about events. Our module is listening and reacting upon events. Tests should triggers these events and observe the expected behavior. The binded method could either be public or private, it doesn’t really matter here as we’re testing the event.

Prefix with ”_”

That’s a largely adopted convention: prefix private methods / variables names with _.

This is also what I do for 2 reasons:

this is a convention which makes things clear. There is no such a thing than private in JS, but most of developers will understand the prefixed method is “supposed” private…
this can ease automated documentation plugins work. If you’re lucky, the doc autocompletion will understand the method is private and won’t forget about the @private.

Finally, it’s about readability. The private nature of the _joke() method is explicit.

However, it’s a common practice that this convention is used to try to define the private nature of a method, instead of just make it explicit. That means the public interface is composed with methods prefixed with _ to tell those should be considered as private.

This is a hot point, with a lot of debates. On my own experience, this is generally something which appears when you don’t really know how to really set up privacy. Everything is public then, but you tell some methods are private by intention.

It’s relatively easy to introduce privacy with the module pattern in fact. Then, my advice would be to consider everything that is exposed as public. If you actually want a method to be private, let’s make it actually private and use the _ prefix for code readability.

That said, projects should define and follow convention that fit their need.

It’s not part of the prototype… what about inheritance and performance?

That’s true. As long as it is not reachable, a private method can’t be inherited. This is basically why I consider private method as a way to simplify the exposed interface of my module. If I need the implementation detail, if I need to access it by inheritance, then I need this detail to be public.

Here again, scepticism is not really caused because of the nature of private methods, but because of a clumsy interpretation / implementation of these.

A note on performance: there will be as much private methods as instances of the module, which is technically less performant. But, having look the actual impact, I think this remark belongs to premature optimization for my current use of privacy.

How do I access public methods from private ones?

That could be blocking.

In fact, if my private method came from a public method refactor, this is not blocking at all. Just because my private method is meant to simplify the public interface, to make the public method more readable.

From my point of view, the private method is kind of a own helper for the module, which helps him to perform its job. Every variable the method needs should be passed as parameters.

Doing so, you can even pass the public interface context to the private method:

var MyModule = (function() {
  var _addSomeCats = function(context) {
    context.cats++
    context.logNumberOfCats()
  }

  return {
    cats: 1,
    addSomeCats: function() {
      // This is not really useful to wrap the whole thing in
      // a private method, but that's a way to illustrate how
      // you can pass it the context.
      _addSomeCats(this)
    },
    logNumberOfCats: function() {
      console.log(this.cats)
    },
  }
})()

Will give you:

MyModule.addSomeCats() // returns "2"

In this example, I’m passing the context as a parameter.

Actually, it’s possible to use this in the _addSomeCats method and then call it with the context bound, thanks to .call() this way: _addSomeCats.call( this );.

Previous example is not a such a big deal, but here’s what it could looks like in an actual project:

var MyModule = (function() {
  // alt. syntax for `var _createViewInstance = function() { … }`.
  // we refactor here some repetitive tasks of the module.
  function _createViewInstance(View, $parent) {
    if (!View) throw new Error('No View constructor provided')
    if (!$parent) throw new Error('No $parent provided')

    var view = new View()
    view.$el.appendTo($parent)
    view.render()

    return view
  }
  // …

  return {
    onRender: function() {
      try {
        this.ordersView = _createViewInstance(this.OrdersView, $('#orders'))
      } catch (err) {
        app.err(err) // -> our way to log errors that would occur
        this.ordersView = {}
      }

      // a bunch of other stuff…
    },

    // …
  }
})()

Which leads you directly to Backbone.js.

Implementation with Backbone.js

This is the main reason for this post. After you understood the concept and mastered the way you set up actual privacy with a module, you could end up puzzled on how to implement that when you usually deal with this:

var MyModule = (function() {
  var Books = {}

  Books.Model = Backbone.Model.extend({
    // a bit of configuration…

    isPrivate: function() {
      console.log('certainly not…')
      return false
    },

    _intendedToBePrivate: function() {
      // kind of method that would pop with this implementation.
    },
  })

  // …

  return Books
})()

Finally, it’s that simple: .extend() will accept an object. Alright, let’s give him an IIFE that will return this object — its API.

var MyModule = (function() {
  var Books = {}

  var ModelConfiguration = (function() {
    var _actuallyPrivate = function() {
      console.log("look 'ma, I'm private!")
    }

    // expose the configuration.
    return {
      defaults: {
        isCompleted: false,
      },

      urlRoot: '/order',

      isCompleted: function() {
        _actuallyPrivate()
        return this.get('isCompleted')
      },
    }
  })()

  Books.Model = Backbone.Model.extend(ModelConfiguration)

  // …

  return Books
})()

Last words

Private methods in JavaScript is a subject that can feeds a lot of debates and one can remain skeptical about that. Sometimes — often? — it makes the whole thing more complex. That’s why I think every project should adopt the position that correspond the best to their needs.

For my part, I create private methods during refactor step. If the method is public by nature, I’ll treat it as such: no _ prefix, unit tests. The most important thing for me is not fooling myself with a convention.

However, I struggled for some time to imagine how it could work using Backbone.js. As it takes me some time to work the whole thing out, here is my contribution post to help those who may enter the same reflexion I’ve had.

That said, this is a subject full of debates and interesting reflexions. Don’t hesitate to share suggestions and remarks if you’re passing by!

Nettoyer son dépôt git, like a boss

Wed, 23 Apr 2014 00:00:00 GMT

Le contexte

Un dépôt git, à l’image du projet qu’il contient, peut avoir une vie longue et tumultueuse au cours de laquelle les conventions évoluent avec nos connaissances et notre maîtrise du schmilblick.

Aussi, il se peut que ce jour arrive où vous contempliez votre projet et réalisiez qu’en fait non, ce n’était pas une si bonne idée que de versionner ces librairies externes / fichiers compilés / vidéos et autres assets / <votre boulette ici>.

Pour ma part, j’ai pas mal enchaîné les boulettes avec le temps :

une fois, j’ai réalisé un peu tard que versionner un paquet de fichiers audio dans un projet l’alourdissait de manière indécente. 5 minutes pour faire un git clone, c’est un peu ouate-ze-foque.
il n’y a pas si longtemps encore, j’ai même réussit à versionner l’ensemble du dossier vendor/ d’un projet s’en m’en rendre compte. Et vlan les jolies stats GitHub du projet ; difficile de suivre son activité quand on a un pic de 20.000 modifications la première semaine.

Or c’est dans ce genre de cas qu’on réalise que :

il est inutile de revert le(s) commit(s) fautif(s), ça ne supprimera pas les modifications indexées dans l’historique
le projet n’est plus tout jeune, ça nous ferait mal de rebase les commits des 3 derniers mois et perdre l’auteur / la date de ceux-ci en les ré-écrivant
et même que parfois on a commit ses fichiers fautifs par-ci par-là au milieu d’autres modifications d’un beau commit

Un dernier cas de figure ? Suffit d’imaginer Bernard qui, s’en trop le vouloir, a commit par erreur des informations un peu confidentielles dans un fichier de conf d’environnement qui n’aurait jamais du être versionné (sisi, ça arrive).

Bref, c’est dans ce genre de situation qu’on se résigne ou que l’on retourne l’Internet en quête de la commande git magique. Et ça tombe plutôt bien, parce-que c’est celle-là même que je vais vous proposer (enfin celle que je connais).

Magic happens here

Admettons par exemple que je souhaite supprimer tous les MP3s versionnés par erreur dans l’ensemble de mon projet. Et ce, sans changer les auteurs des commits, ni même les dates, mais en supprimant tout de même toute trace de ces fichiers (histoire de réduire considérablement la taille de mon dépôt, par exemple).

Et donc pour cela, j’ouvre mon terminal et je lance l’incantation suivante :

git filter-branch -f --tree-filter "rm -rf \*.mp3" --prune-empty -- --all

Ce qui me permet donc, en partant de ce genre d’historique :

De me retrouver avec un dépôt propre comme un sous neuf :

Les dates de commit sont conservées, les auteurs aussi, ce qui ne serait pas le cas avec un rebase classique. Toutefois, l’historique est bel et bien ré-écrit : les SHA1 des commits qui ont été modifiés sont différents.

C’est sorcellerie !?

Voyons un peu ce que ce que cache cette loooongue commande magico-magique.

`git filter-branch`

La commande filter-branch de git permet de ré-écrire un grand nombre de commits de manière scriptable. Autrement dit, c’est ce qui va permettre de ré-écrire complètement l’historique en fonction des paramètres que nous allons passer ensuite.

`-f`

L’option -f permet de forcer le démarrage de git filter-branch si jamais il y a déjà un dossier temporaire refs/original/ pré-existant. Git s’en sert pour faire une sauvegarde de l’historique avant de partir à l’aventure.

Le -f n’est donc pas obligatoire mais si le backup ne peut pas être créé, git vous dira de relancer la commande avec cette option.

`--tree-filter "<shell command>"`

Cette option va vous permettre de passer en revue chacun de vos commits et d’y exécuter la commande que vous aurez passé en paramètre.

Pour ma part, j’ai utilisé rm -rf *.mp3 pour m’assurer de bien supprimer l’ensemble des fichiers MP3s qui pouvaient être versionnés. Dans un tel cas, il faut s’assurer de forcer la commande (d’où le -rf) car le nettoyage s’arrête s’il y a une erreur à base de fichier-mp3-non-trouvé-dans-ce-commit.

Note - Au cas où vous ne voudriez pas vraiment supprimer les fichiers mais juste les retirer de l’historique git, préférez l’utilisation de la commande —index-filter “git rm -rf —cached —ignore-unmatch *.mp3” à la place.

`--prune-empty`

On s’assure de bien supprimer les commits qui seraient éventuellement vides, une fois l’historique nettoyé.

`-- --all`

Le premier -- permet de distinguer --all comme une options supplémentaire, et non pas un paramètre de --prune-empty. Et donc cela permet de dire à git de réaliser son opération sur toutes les branches de l’historique.

Le mot de la fin

Si vous travaillez à plusieurs sur le projet, n’oubliez pas que ré-écrire l’historique, c’est pas anodin (et ce, peu importe la méthode). Du coup, si vous êtes amené à faire ce genre de manipulation pour le bien du dépôt, le plus simple reste pour les autres de re-cloner le nouveau dépôt tout propre, tout simplement.

Et si vous craigniez que votre manipulation ne fonctionne pas comme prévu, clonez simplement le dépôt quelque part avant de faire votre tambouille et vous pourrez toujours le récupérer si jamais ça ne se passe pas bien.

Note - Une bonne idée serait de faire ce genre d’opérations dans un branche à part. Si le résultat est convaincant, alors il n’y aura plus qu’à faire un reset hard de master sur cette branche.

Voilà, en espérant que ça puisse vous dépanner… mais que vous n’ayez pas à vous en servir trop souvent !

Clean your git repo, like a boss

Wed, 23 Apr 2014 00:00:00 GMT

The context

The life of a git repo could last and change a lot. Conventions often move with our knowledge and mastering of that stuff.

And there comes the day where you look at your project and realize that it wasn’t such a good idea to commit those external libraries / compiled outputs / videos and other media / <your error here>.

I personally did a bunch of mistakes with git:

one day I realized a bit late that if you commit a lot of audio files in your project, then you’ll make it grow insanely. 5 minutes to perform a simple git clone is waaaaaay toooo looooooong.
few time ago, I even managed to commit the whole vendor/ folder of a project by mistake. It didn’t play well with the nice GitHub stats of the project. That’s a tough job to follow the activity of the team when there is a 20.000 updates peak on the very first week.

And then you realize that:

it’s pointless to revert the faulty commit(s), it won’t remove the indexed modifications from the history
the project may not be young, it’d be sad to rebase and re-write every commits from the last 3 months and loose information such as the author / the date
and even sometimes you’ll have your faulty files committed with other fixes and killer-features

Need another use case? Just think about Bernard who committed confidential information in a environment config file which should never have been versioned -have you heard about a guy called Murphy?.

Now you can figure out that situation when you open the Internet, searching for the magic git command. Here you go, this is precisely what’s this post about -at least, the magic command I know.

Magic happens here

Let’s say I would like to remove every MP3 files committed by mistake from a whole project. Plus, I don’t want to change the author of each commit, neither the date - but still I want to remove all trace from those files in the history to reduce the size of my repo.

To do so, I mystically wave my hand in the air and write the following incantation with the other:

git filter-branch -f --tree-filter "rm -rf \*.mp3" --prune-empty -- --all

Which would transform this history:

Into this clean and shiny one:

Dates and authors are still there, which wouldn’t have been true with a classic rebase. Still, the history has been rewritten: SHA1 of commits which have been rewritten are different.

It’s a kind of magic

Let’s see what is this looooong mystical command about.

`git filter-branch`

The filter-branch command will rewrite a large number of commit in a scriptable way. In other words, it will rewrite the history regarding the options you give.

`-f`

The -f option forces git filter-branch to start even if there is an existing temporary refs/original/ directory already. Git will use this directory to perform some backup before going further.

It’s not mandatory then, but if the backup can’t be created, git will tell you to use it anyway.

`--tree-filter "<shell command>"`

This option will check every commit of your tree and execute the given shell command.

I previously used rm -rf *.mp3 to ensure there will not be any MP3 file surviving this operation. In this case, I needed to ensure the command is forced -this is for the -rf part- so the cleaning won’t stop if there is an error because of no-mp3-file-in-this-commit reason.

Note - In case you don’t want to actually delete these files but just remove them from the git history, prefer to perform a —index-filter “git rm -rf —cached —ignore-unmatch *.mp3” instead.

`--prune-empty`

We prune any commit that would eventually be empty after we cleaned the history.

`-- --all`

The first -- will ensure we don’t consider --all as a parameter for --prune-empty, but as another option. And so git will consider every branches of the history to perform the cleaning here.

Final words

If you’re many to work on the project, please remember that rewrite the history is not a genuine action, whatever the method you use. Then, if you really need to do that kind of manipulation, it will be easier for you colleagues to simply clone the new shiny repo.

If you fear that your manipulation won’t work as expected, just clone the repo somewhere else before doing your stuff. So you’d be able to get it back in case something is going wrong.

Note - A good idea is to perform that kind of operations in another branch. If you’re satisfied with the result, just reset hard the master branch onto this one and you’re all set.

Here you go. I hope that could help you… but that you won’t need to use it too often!

Un blog multilingue avec Jekyll 1.5

Sat, 05 Apr 2014 00:00:00 GMT

Note sur la compatibilité

Ce qui suit se base sur l’utilisation de Jekyll v1.5.1.

Ce post fait suite à celui de Mai 2013 où je vous faisais mon retour d’expérience sur la création d’un blog en plusieurs langue. Depuis Jekyll a (sérieusement) monté en versions et voici les correctifs à apporter en ce sens.

Petit rappels sur Jekyll

Après bientôt une année d’utilisation (quoiqu’ayant écrit peu d’articles ces derniers mois), voilà ce que je retiens de Jekyll :

c’est la solution la plus simple pour réaliser un site web front-end avec le confort de la compilation (templates, plugins, etc.). Bien entendu, le fait que GitHub le prenne en charge nativement joue beaucoup en ce sens.
il bénéficie des avantages et inconvénients de Ruby on Rails (la beauté du langage, la prise de tête de la montée en versions)
écrire ses articles en Markdown, c’est vraiment pratique
si le fonctionnement standard ne nous convient pas, libre à nous de le surcharger avec nos propres plugins

En revanche, si vous élaborez vous-même vos plugins, il vous faudra compiler tout d’abord votre site pour envoyer la version statique sur GitHub.

Speaking Français, ze retour

Pour rappel, voici à quoi ressemble l’architecture de mon blog :

.
|-- _data/ # Stock de variables et configuration
|-- _includes/ # Bouts de codes inclus ailleurs
|-- _layouts/ # Templates du site
|-- _plugins/ # Plugins pour surcharger de Jekyll
|-- assets/ # LESS/CSS, JS, images, …
|-- fr/ # Categorie FR
| |-- _posts/ # Articles en français
| |-- index.html # Pages html en français
| |-- about.html
| |-- (…)
|
|-- en/ # Catégorie EN
| |-- _posts/ # Articles en anglais
|
|-- index.html # Pages html par défaut (EN)
|-- about.html
|-- (…)
|-- _config.yml # Fichier de configuration de Jekyll

Lorsqu’il est lancé, Jekyll génère le site statique final dans le dossier _site/. C’est cette version qui est envoyée (et servie) sur GitHub.

Note - J’ai retiré de _config.yml les variables qui dépendent de la langue et que je réutilise dans les templates.

Elles sont désormais isolées proprement dans le fichier _data/locales.yml.

Naturellement, mettre à jour Jekyll de la v0.12 à la v1.5 a nécessité quelques arrangements dans le fichier config.yml, histoire de retirer ce qui était deprecié et ajouter ce qui manquait.

Egalement, il a fallu toucher aux plugins…

Les plugins, ce qui a changé

1. Pagination par catégorie

C’est LE plugin qu’il a fallu modifier, le fonctionnement de la pagination ayant radicalement changé avec Jekyll.

N’ayant rien trouvé de convaincant, j’ai ré-écrit mon propre plugin category_pagination.rb.

Ajoutez-le simplement à votre dossier _plugins/, puis configurez votre config.yml en fonction du comportement attendu :

paginate_per_category: true si vous souhaitez activer le plugin
default_category: "en" (optionnel) si vous souhaitez que la pagination à la racine du projet ne prenne pas en compte tous les posts, mais uniquement ceux d’une catégorie

Le plugin fonctionne très simplement :

si je cherche à paginer à l’intérieur d’une catégorie (aka dossier),
la pagination ne considèrera que les posts de cette catégorie,
je peux définir une catégorie par défaut pour les fichiers qui se trouvent à la racine si je le souhaite (sinon, ça pagine tout).

Je vous laisse jeter un oeil à fr/index.html si besoin.

Note - C’est un premier jet qui peut aussi servir de pagination par catégorie de manière assez simpliste et orientée. N’hésitez pas à proposer des améliorations =)

2. Filtre i18n

i18n_filter.rb customise le traitement de page.date en fonction de la langue.

J’ai du ajouter un fichier _locales/fr.yml afin de créer la fonction localize. Elle fonctionne de la même manière que date mais renvoie le format français de la date.

Et voilà !

Rien d’autre n’a vraiment changé, juste ces correctifs à apporter et le tour est joué. Si vous avez des suggestions, remarques ou soucis avec tout ça, faîtes-le moi savoir.

Plop !

Multilingual blog with Jekyll 1.5

Sat, 05 Apr 2014 00:00:00 GMT

Note on compatibility

This post considers you’re using Jekyll v1.5.1.

It’s an extension to my previous post from April 2013 in which I explained how I managed to build this English-French blog. There have been a bunch of new versions of Jekyll since. I’ll explain here how to change the previous implementation accordingly.

Few reminders about Jekyll

After almost one year using it - even though I didn’t write that much post these months - here is what I could take from Jekyll:

this is the simplest solution to build a front-end website with the ease of compilation (templates, plugins, etc.). The fact that GitHub takes in charge the compilation helps that point of view, for sure
it takes advantages and inconveniences from Ruby on Rails - the beauty of the language, the nightmare of the version upgrade
writing posts in Markdown is a no-brainer
if standard behavior doesn’t fit our needs, we could also override it with our own plugins

Keep in mind that if you’re using plugins, you should compile the website by yourself before sending the static version to GitHub.

Speaking Français, ze retour

As a reminder, here is my blog architecture:

.
|-- _data/ # Variables and configuration
|-- _includes/ # Partials included in other files
|-- _layouts/ # Templates of the website
|-- _plugins/ # Plugins to override Jekyll workflow
|-- assets/ # LESS/CSS, JS, images, …
|-- fr/ # French category
| |-- _posts/ # French posts
| |-- index.html # French html files
| |-- about.html
| |-- (…)
|
|-- en/ # English category
| |-- _posts/ # English posts
|
|-- index.html # Default html files (EN)
|-- about.html
|-- (…)
|-- _config.yml # Jekyll configuration file

Jekyll compile sources and will output them into _site/ folder. This version is sent to GitHub.

Note - I removed from _config.yml language-dependent variables that I can use in my templates…

They are now properly isolated into the _data/locales.yml file.

For sure, upgrading Jekyll from v0.12 to v1.5 leads to some modifications of the config.yml file in order to remove what was deprecated and add what was necessary.

Then come plugins…

Plugins, what has changed here

1. Per-category pagination

This is THE plugin that needed to be changed as Jekyll pagination workflow changed completely.

I didn’t find anything convincing enough, so I wrote my own category_pagination.rb plugin.

Just add it to your _plugins/ folder, then configure your config.yml regarding your needs:

paginate_per_category: true if you wish to activate the plugin
default_category: "en" (optional) if you wish the root pagination to be the one of a specific category

The plugin is pretty straightforward:

if I want to paginate a category (aka folder),
pagination will only consider posts from this category,
I can define a default category for files that are at the root of the project (otherwise I’d paginate everything).

You can have a look to the fr/index.html page.

Note - This is a first draw that could be used as a simple - and opiniated - per-category pagination. Don’t hesitate to suggest improvements =)

2. I18n filter

i18n_filter.rb customize the treatment of page.date variable, regarding the language.

I’ve had to add a _locales/fr.yml file in order to create the localize function. It works just like the date method, but output the french format for the date.

Et voilà!

Nothing has really changed, just few corrections to set and it’s done. If you have any suggestion, remark or issue with that, just drop me a line.

Plop!

Gitgraph.js

Sun, 03 Nov 2013 00:00:00 GMT

Le problème

Il y a quelques temps je rédigeais un article sur les workflows git. Pour illustrer mes propos, je souhaitais m’appuyer sur une représentation visuelle de ces workflows.

Or, si le git-flow propose déjà une illustration sympathique et claire, il n’y a rien de tel pour le GitHub flow par exemple.

Par chance, @nvie donne la source de son illustration. Par chance aussi, j’ai Keynote. J’ai donc pu créer, à la main, ma seconde illustration, pour ensuite l’exporter afin d’obtenir une image à insérer dans mon article.

Si l’opération n’était pas très complexe, pour peu d’avoir les logiciels adéquats, elle n’en reste pas moins frustrante :

et si je veux apporter une petite modification à mon illustration ?
et si je veux changer le style de mon dessin ?
et si je veux rendre le graphe interactif ?
et si je veux apprendre le saxophone ?

La solution

L’idée était donc de trouver une petite bibliothèque JavaScript qui aurait permis de dessiner à la volée des graphes pour illustrer des workflows git (ou équivalents).

N’ayant rien trouvé de convaincant, @fabien0102 et moi avons décidé de la développer : GitGraph.js !

Les guidelines sont les suivantes :

API simple et intuitive
flexibilité et robustesse du résultat
rendu customisable à souhait

Le projet est passé à un état standard satisfaisant pour répondre à nos premiers besoins. Nous avons donc sorti la v1.0.0 (et promis, on suivra scrupuleusement Semver !).

Installation

Plusieurs solutions sont à votre disposition :

soit en téléchargeant l’une des dernières releases sur GitHub
soit en passant par Bower avec bower install gitgraph.js

Mise en place

Le process d’installation est assez simple.

Commencez par ajouter le JavaScript (de préférence avant le </body>) :

<script type="text/javascript" src="js/gitgraph.min.js"></script>

Puis le CSS (de préférence avant le </head>) :

<link rel="stylesheet" type="text/css" href="css/gitgraph.css" />

Enfin, préparez un ou plusieurs <canvas>, identifiés pour GitGraph.js :

<canvas id="my-first-gitgraph"></canvas>
<!-- un peu de HTML ici (…) -->
<canvas id="another-graph-here"></canvas>

C’est bon, vous êtes prêts, yapuka dessiner !

Utilisation - Quelques exemples

L’utilisation de la bibliothèque est assez simple : il suffit de créer un nouveau GitGraph pour un canvas ciblé, puis de dessiner le graphe souhaité.

Un certain nombre de paramètres sont personnalisables à la création, à savoir :

le template désiré : "blackarrow" ou "metro" (par défaut)
l’orientation du graphe : "vertical-reverse", "horizontal", "horizontal-reverse" ou bien "vertical" (par défaut)
le mode d’affichage : "compact" pour masquer les messages de commit, ou "extended" (par défaut, affichage "vertical" seulement pour le moment)
l’ID du canvas ciblé ("gitGraph" par défaut)
l’auteur par défaut pour les commits

On crée donc un nouveau graphe très simplement ainsi :

var monGitGraph = new GitGraph({
  elementId: 'mon-canvas',
})

Puis on peut créer des branches :

var master = monGitGraph.branch('master')

Faire quelques commits :

monGitGraph
  .commit()
  .commit()
  .commit() // 3 commits sur HEAD

Créer une nouvelle branche et committer dessus :

var develop = monGitGraph.branch('develop')
develop.commit() // Ce commit sera sur `develop`

Et faire ce que l’on veut d’ailleurs :

// Une nouvelle branche `feature` depuis `develop`
var myFeature = develop.branch('myFeature')

// Un commit customisé
myFeature.commit({
  dotColor: 'white',
  dotSize: 10,
  dotStrokeWidth: 10,
  sha1: '666',
  message: 'Pimp dat commit',
  author: 'Jacky <prince@dutunning.com>',
})

// Et on ferme la feature dans `develop`
myFeature.merge(develop, 'Epic merge commit')

// Si on ne va plus committer dessus, on peut complètement supprimer la branche
myFeature.delete()

L’idée est que la bibliothèque s’adapte aux usages afin de rester intuitive.

Il reste encore pas mal de fonctionnalités à implémenter et de petits bugs à corriger. Mais si vous vous en servez, n’hésitez pas à nous faire remonter soucis ou suggestions =)

Utilisation - Le résultat

Voyons donc quelques exemples d’utilisation basiques que l’on peut mettre en place actuellement avec la bibliothèque.

Ce JavaScript :

var blackarrowSolution = new GitGraph({
  elementId: 'blackarrow-solution',
  orientation: 'vertical',
  template: 'blackarrow',
  author: 'Nicolas Carlo <nicolascarlo.espeon@gmail.com>',
})

var master = blackarrowSolution.branch('master')
blackarrowSolution
  .commit('This is a commit')
  .commit("And here's another one!")
  .commit()

var develop = master.branch('develop')
develop.commit('My first commit on develop.')

var feature = develop.branch('feature')
feature
  .commit('This is a mandatory feature')
  .commit()
  .commit()
develop.commit('Meawhile, we commit on develop…')
feature.merge(develop, 'Merged into develop')
feature.delete()

develop.commit('Add some commit here…').commit()
develop.merge(master, 'Here we merge!')
master.commit().commit()

Produira le résultat suivant :

Tandis que ce code :

var metroSolution = new GitGraph({
  elementId: 'metro-solution',
  orientation: 'horizontal',
})

var master = metroSolution.branch('master')
metroSolution
  .commit()
  .commit()
  .commit()

var develop = master.branch('develop')
develop.commit().commit()

develop.merge(master, 'Here we merge!')
master.commit().commit()

Donnera ce graphe :

Le projet

Le projet est open-source, disponible sur GitHub : https://github.com/nicoespeon/gitgraph.js

N’hésitez pas à ajouter une issue pour toute remarque / suggestion / correction à apporter au projet, voir à y contribuer. La documentation technique du code est également disponible. Une documentation plus fonctionnelle est également envisagée, avec le support d’exemples concrets.

Le projet est publié sous license MIT, simple et permissif.

En attendant, vous pouvez toujours allez jeter un oeil au site pour plus d’informations sur la prise en main de la bibliothèque : gitgraphjs.com.

Hey mais et le sax dans tout ça ?

Ma foi il n’y a qu’à demander, sur ce je vous laisse sur un petit air de Georges Michael \o/

Gitgraph.js

Sun, 03 Nov 2013 00:00:00 GMT

The problem

Few time ago I was writing a post about git workflows. I wish I could use some illustration to explicit my thoughts at this time.

The git-flow already provided a nice illustration of the big picture for this workflow. But the GitHub flow didn’t.

Hopefully, @nvie gave its Keynote source and, hopefully, I’ve got Keynote. Therefore I designed the second illustration myself, exported it and then get an image to insert in my post.

It was not a difficult operation, as long as you get the correct tools. But this is frustrating:

what if I want to do a little update?
what if I want to change the whole design?
what if I want to add some interaction?
what if I want to learn saxophone?

The solution

I wish I could find a nice little JavaScript library to design on-the-go graphs to illustrate my git worflows.

But, as we didn’t find anything convincing enough, @fabien0102 and I decided to develop our own solution : GitGraph.js !

Our guidelines are the following :

simple and intuitive API
flexibility and robustness of the result output
customisable design

The project reached a convincing state, stable enough to meet our first requirements. And so we released v1.0.0 and we’ll scrupulously follow Semver, promise!.

Installation

Different solutions are available:

you can either download one of the latest releases sur GitHub
you can either use Bower with bower install gitgraph.js

Setting up

The set up process is dead easy.

Start adding the JavaScript (preferably before </body>) :

<script type="text/javascript" src="js/gitgraph.min.js"></script>

Then add the CSS (preferably before </head>) :

<link rel="stylesheet" type="text/css" href="css/gitgraph.css" />

Then, prepare some <canvas>, identified for GitGraph.js use :

<!-- some HTML here (…) -->
<canvas id="another-graph-here"></canvas>

Here we go!

Usage - Some examples

Using the library is straightforward : you just need to create a new GitGraph for each canvas, then to draw the desired graph.

Some parameters are customisable when you create your graph:

the desired template: "blackarrow" or "metro" (default)
the graph orientation: "vertical-reverse", "horizontal", "horizontal-reverse" or even "vertical" (default)
the display mode: "compact" to hide commit messages, or "extended" (default, only with a "vertical" display for now)
the targetted canvas ID ("gitGraph" is the default)
A default author for commits messages

And so we create our very first graph this way:

var myGitGraph = new GitGraph({
  elementId: 'my-canvas',
})

Then we add some branches:

var master = myGitGraph.branch('master')

A bunch of commits:

myGitGraph
  .commit()
  .commit()
  .commit() // 3 commits upon HEAD

Let’s create a new branch and add few commits:

var develop = myGitGraph.branch('develop')
develop.commit() // This commit will be on `develop`

Let’s do whatever we want:

// A new `feature` branch from `develop`
var myFeature = develop.branch('myFeature')

// A custom commit
myFeature.commit({
  dotColor: 'white',
  dotSize: 10,
  dotStrokeWidth: 10,
  sha1: '666',
  message: 'Pimp dat commit',
  author: 'Jacky <mailto:prince@dutunning.com>',
})

// Merge our feature branch back into `develop`
myFeature.merge(develop, 'Epic merge commit')

// Well we don't want to use it again, let's delete the old feature branch now
myFeature.delete()

The idea is to adapt the library to your needs so it could be intuitive.

There is still a lot of features to implement and bugs to correct. Please give us some feedbacks if you try it, that would be awesome =)

Usage - The result

Here are some basic use cases that could already be answered with the library.

This JavaScript:

var blackarrowSolution = new GitGraph({
  elementId: 'blackarrow-solution',
  orientation: 'vertical',
  template: 'blackarrow',
  author: 'Nicolas Carlo <mailto:nicolascarlo.espeon@gmail.com>',
})

var master = blackarrowSolution.branch('master')
blackarrowSolution
  .commit('This is a commit')
  .commit("And here's another one!")
  .commit()

var develop = master.branch('develop')
develop.commit('My first commit on develop.')

var feature = develop.branch('feature')
feature
  .commit('This is a mandatory feature')
  .commit()
  .commit()
develop.commit('Meawhile, we commit on develop…')
feature.merge(develop, 'Merged into develop')
feature.delete()

develop.commit('Add some commit here…').commit()
develop.merge(master, 'Here we merge!')
master.commit().commit()

Will produce the following output:

While this code:

var metroSolution = new GitGraph({
  elementId: 'metro-solution',
  orientation: 'horizontal',
})

var master = metroSolution.branch('master')
metroSolution
  .commit()
  .commit()
  .commit()

var develop = master.branch('develop')
develop.commit().commit()

develop.merge(master, 'Here we merge!')
master.commit().commit()

Will output this graph:

The project

Our project is open-source, available on GitHub : https://github.com/nicoespeon/gitgraph.js

Feel free to add an issue for any remark / suggestion / correction you’d have to do, or even to contribute more deeply. A technical documentation for the source code is available. A much more functional one is already considered, with concrete examples and use cases.

The project use the MIT license, which is simple and permissive.

Have a look to the website for more information about the library: gitgraphjs.com.

Hey, what about the sax?

I was afraid you wouldn’t ask. Thereupon I leave you with some Georges Michael tune \o/

Quel git workflow pour mon projet ?

Thu, 15 Aug 2013 00:00:00 GMT

TL;DR

L’une des grandes forces de git réside dans la simplicité de son système de branches.
Si vous êtes en charge d’un projet, peut-être vous êtes-vous déjà posé la question : quel workflow mettre en place pour gérer efficacement mon projet, sans me compliquer la vie avec ce sympathique système de branches ?

Et forcèment : à ce problème, certains s’y sont déjà penchés et ont apporté leurs solutions.

Le git-flow est probablement le plus connu, voire le seul d’ailleurs.
Il s’agit d’un modèle de branches standard qui semble s’adapter à n’importe quel projet, pas trop complexe à prendre en main, avec quelques subtilités cependant.

Si la notion de versions a un sens pour votre projet, c’est ce workflow qui peut vous intéresser.

Il existe une alternative pertinente qui a l’avantage d’être bien plus simple : le GitHub flow.

Le modèle tient en 6 règles simples qui n’ont pas besoin de prendre en compte les subtilités du workflow précédent.

Si la notion de versions n’a pas spécialement de sens pour votre projet et que vous souhaitez mettre en place un workflow simplifié, c’est ce workflow qui peut vous intéresser.

Le git-flow

Ce workflow a été présenté le 5 Janvier 2010 par Vincent Driessen comme un workflow de branchements git efficace. Il couvre l’ensemble des besoins standards d’un projet de développement classique.

Le principe

Le git-flow présente le système de branches suivant :

Le modèle git-flow illustré

On distingue les branches principales, fixes et immuables :

master est la branche où tout est stable. Chaque commit correspond à une version stable du projet (release) qui peut être déployée en production et taguée en conséquence (vX.Y.Z).
develop est la branche sur laquelle s’effectue le développement proprement dit. On y prépare les changements en vue de la prochaine release dans master.

Puis les branches secondaires qui se font et se défont avec le temps :

feature part de develop et se merge dans develop.

On crée une branche feature/xxx lorsque l’on travaille sur une fonctionnalité en particulier. Lorsqu’elle est terminée, on la merge dans develop pour ajouter la feature stable dans le scope de la prochaine release.
release part de develop et se merge dans master et develop.

On crée une branche release/xxx à partir de develop lorsque celle-ci reflète l’état désiré de la release (l’ensemble des fonctionnalités du scope ont été mergées). Ainsi, on peut préparer la prochaine release tranquillement, corriger d’éventuels bugs et poursuivre le développement en parallèle.

Une fois que la release est prête (stable) on merge alors la branche dans master, mais aussi dans develop pour mettre à jour les modifications apportées.
hotfix part de master et se merge dans master et develop / release.

On crée une branche hotfix/xxx lorsque l’on veut résoudre un bug critique en production rapidement. C’est un peu comme une release non planifiée.

Lorsque le correctif est développé, on le merge dans master avec le numéro de version qui convient, ainsi que dans develop (ou la branche release en cours, le cas échéant) pour mettre à jour les modifications apportées.

Liens utiles

Je vous suggère de jeter un oeil sur l’article original pour en apprendre plus sur la question.

Pour vous simplifier la vie dans le terminal, sachez que l’auteur a également mis au point une extension git pour implémenter simplement le git-flow.

Enfin, pour les utilisateurs de SourceTree, sachez que ce workflow est nativement implémenté.

Si vous êtes sous Windows ou Mac et que vous cherchez un bon client graphique pour git/mercurial, je vous recommande chaudement d’essayer SourceTree d’ailleurs !

Le GitHub flow

Scott Chacon l’a présenté dans un post le 31 Août 2011. Il s’agit d’une version allégée du précédent et découle, en quelque sorte, du bon sens.

A noter que je garde ici la référence à GitHub par rapport au superbe post de Scott mais Atlassian (Bitbucket) le présente, par exemple, comme le workflow feature branch.

Le principe

Je me suis permis d’illustrer le GitHub flow de la manière suivante :

Le modèle GitHub flow illustré

Vous constaterez qu’il n’y a qu’une seule branche master (pas de develop ici) et des features à gogo. Il est frappant de constater que le modèle est extrêmement simple et c’est le but. La courbe d’apprentissage est faible, les développeurs prennent rapidement en main ce workflow qui s’avère parfaitement adapté dans certains cas de figures.

Ce workflow se base donc sur 6 règles essentielles :

1. Tout ce qui est dans `master` peut être déployé en production

La règle absolue, commune au git-flow d’ailleurs. C’est la seule branche consistante du projet et elle doit rester stable pour pouvoir se baser dessus et être déployée en production.

2. Créer des branches explicites depuis `master` (features)

Lorsqu’on souhaite travailler sur quelque chose (une fonctionnalité, un hotfix, etc.), on crée une branche depuis master avec un nom explicite, si possible : bug-grunt-tests, infrastructure-ssl ou module-game-workers sont des exemples tirés d’un projet sur lequel je travaille actuellement par exemple.

3. Pousser sur `origin` régulièrement

Contrairement au git-flow, où le développeur ne va pas forcément pousser sa branche feature locale sur le dépôt central, il s’agit ici de pousser les branches régulièrement.

En effet, tant que nous ne sommes pas sur master il importe peu que la branche soit stable. En contrepartie, cela permet de communiquer avec l’équipe.

4. Ouvrir une pull-request à tout moment

Si votre projet est hébergé sur GitHub ou Bitbucket, sachez que les deux proposent une fonctionnalité extrêmement intéressante pour la revue de code : les pull-request.

Il est très facile, depuis une branche, de faire un diff avec master et d’ouvrir une pull-request à n’importe quel moment : que l’on pense avoir terminé ou que l’on soit coincé, la pull-request permet de demander une revue du code. Il est alors possible de commenter le code, d’apporter des modifications et de visualiser ce que l’on s’apprête à fusionner dans master.

5. Fusionner seulement après une pull-request review

Il s’agit plus d’un conseil que d’une règle absolue. Mais c’est la bonne pratique à mettre en place pour s’assurer que la première règle est respectée : un développeur ne doit pas fusionner sa branche dans master lorsqu’il pense que c’est bon, un autre doit venir faire une revue du code et confirmer la stabilité de la branche.

Ainsi, si le merge vient mettre la pagaille sur master, on sait sur qui taper… 0:-)

Vous pouvez alors :

fusionner la branche dans master, directement depuis la pull-request
supprimer la branche, devenue inutile, sur le serveur

Si cela fait un moment que vous travaillez sur votre branche et que vous n’êtes plus synchro avec master, vous ne pourrez pas fusionner directement depuis la pull-request car il y aura des conflits. Il vous suffit de faire un merge de master dans votre branche et règler les potentiels conflits pour la mettre à jour.

6. Déployer immédiatement après merge dans `master`

Une fois que la pull-request est validée, la branche est mergée dans master ce qui signifie que le tout est déployé en production (ou va être déployé sous peu).

C’est également une façon d’accentuer la pression sur la nécessaire stabilité de master : le développeur ne souhaite généralement pas que le déploiement de ses modifications ne casse tout, il fera donc d’autant plus attention à la stabilité de son code avant de fusionner.

Quelques remarques

Ce genre de workflow s’adapte parfaitement à un projet pour lequel il n’y a pas vraiment de releases, ni de versions.

On intègre en continue dans master les fonctionnalités et on déploie, parfois plusieurs fois par jour, le projet stable. On revient assez rarement (jamais) en arrière sur master.

Ainsi, il est difficile d’ajouter une série de gros bugs. Si des problèmes apparaissent, ils sont rapidement résolus dans la foulée. Il n’y a pas de différence entre une grosse feature et un petit hotfix avec ce process. Peu importe la nature du changement à effectuer, le workflow est toujours le même (et donc très simple à prendre en main).

Liens utiles

Je vous suggère là encore de jeter un oeil sur l’article original pour en apprendre plus sur la question.

Techniquement, GitHub a fait en sorte de vous permettre de gérer ce workflow entièrement, directement depuis le navigateur. Bitbucket se débrouille pas mal non plus.

Si vous en ressentez le besoin, il y a également une extension git pour implémenter le workflow. Mais dans l’ensemble, il se manie assez bien dans le navigateur.

Le mot de la fin

Choisir son workflow dépend de la nature et des besoins de son projet. A vous de voir si ces exemples s’adaptent plus ou moins à votre réalité, quitte à faire quelques adaptations si nécessaire.

Voici donc pour les workflows que j’utilise, n’hésitez pas à partager d’autres pistes, d’autres idées.

Which git workflow for my project?

Thu, 15 Aug 2013 00:00:00 GMT

TL;DR

One of the greatest strenght of git is the simplicity of its branching system.

If you’re in charge of a project, you may have wondered: which workflow could I set up to efficiently deal with my project and keep it simple thanks to this cool branching system?

As usual: some people already wondered the same and have found possible solutions to your problem.

The git-flow is the most popular with no doubt.

It’s a standard branching model that seems to adapt to any project, not that complex to deal with even though there are some specificities to understand.

If versioning has a meaning for you project, this workflow is for you.

There is a relevant alternative that is far easier: the Github flow.
This model has 6 simple rules and doesn’t have to consider every subtleties the previous one does.

If versioning doesn’t have a particular meaning for you project de sens and you would like to use an easy workflow, this workflow is for you.

The git-flow

This workflow has been published the 5th of January, 2010 by Vincent Driessen as a successful branching model for git. It covers most of the standard needs for a classical development project.

How it works

The git-flow has the following branching model:

The illustrated git-flow model

We have first the primary branches, fixed and unchanging:

master is the main branch where everything is stable. Each commit is a stable version of the project - a release - which could be deployed in production and tagged accordingly (vX.Y.Z).
develop is the main branch where development is made. There will be prepared changes for the next release in master.

Then come the secondary branches which are flexible over time:

feature starts from develop and merge into develop.

When you’re working on a specific feature, you create a feature/xxx branch. Then, when it’s over, you merge it back into develop to add the stable feature to the scope for the next release.
release starts from develop and merge into master or develop.

When develop is reflecting the desired state of the future release - every features from the scope have been merged -, you create a release/xxx branch. Doing so, you can prepare the next release, correct eventual bugs and continue the development in parallel.

Once the release is ready - stable - you merge the branch back into master, but also into develop to update it with modifications you made.
hotfix starts from master and merge into master or develop / release.

When you want to quickly resolve a critical bug in production, you create a hotfix/xxx branch. It’s kind of a non-planned release.

When the hotfix is developed, you merge it back into master with the according version number, and into develop as well - or the according release branch, if so - to update it with modifications you made.

Useful links

You might have a look at the original post to go deeper into details.

To make it simple when using the terminal, the author also created a git extension that easily implement the git-flow for you.

By the way, if you use SourceTree you may know that this workflow is natively implemented.

If you are a Windows or Mac user and you’re searching for a good graphic client for git/mercurial, I warmly recommend you to try SourceTree!

The GitHub flow

Scott Chacon shared this workflow in a blog post the 31th of August, 2011. It’s kind of a lightwight version of the previous one which, with a lot of common sense.

You’ll notice that I kept the reference to GitHub because of the Scott’s blog post, but Atlassian - Bitbucket - presented it as the feature branch workflow for instance.

How it works

I have taken the liberty to illustrate the GitHub flow as follows:

The illustrated GitHub flow model

You’ll notice that there is only a single master branch - no develop - and a bunch of features. This model is extremely simple and this is precisely the goal. The learning curve est low, developers can quickly master this workflow which is perfectly relevant in some cases.

This workflow follows 6 basic rules:

1. Everything that is in `master` could be deployed in production

The absolute rule, same as the git-flow by the way. This is the only meaningful branch of the project and it should stay stable in any circumstance so you can base your work upon and deploy it in production at anytime.

2. Create descriptive features branchs from `master`

When you want to develop a feature or a hotfix, for instance, you just create your branch from master with an explicit name that describe your work: bug-grunt-tests, infrastructure-ssl or module-game-workers are examples from a project I currently work on, for example.

3. Regularly push to `origin`

In contrary of the git-flow where developer doesn’t have to push its local feature branch to the main repo, you have to regularly do that here.

Indeed, as far as you’re not on master, the stability of the branch doesn’t really matter. Doing so allows you to communicate and share your work with the whole team.

4. Open a pull-request at anytime

If your project is hosted on GitHub or Bitbucket, you should know that they both propose an incredibly interesting feature for code review: pull-requests.

It’s dead easy then, from any branch, to make a diff with master and open a pull-request at anytime: either you think you’re done or stuck on something, the pull-request allows you to ask someone else to have a look on what you did. Then, it’s possible to comment code, add modifications and visualize precisely what you’re about to merge into master.

5. Only merge after a pull-request review

This is much more and advice than an absolute rule. It’s a best practice that you can use to be sure that the first rule is less likely to be broken, still: a developer should not merge its own branch into master when he thinks he is done. Another one should review his pull-request and confirm that the branch is stable.

Doing so, if master becomes a mess because of this merge, you know who gave his agreement… 0:-)

From here you can:

merge the branch back into master, directly from the pull-request
delete the merge branch, which became useless, on the server

If you are not synchronized anymore with master because you spend a long time working on your branch, you can’t merge directly the pull-request because there would be conflicts. You just need to merge master into your branch before, so you can fix conflicts and update your feature before merging it back into master.

6. Immediately deploy after you merge into `master`

Once pull-request is valid, your branch is merged into master so it means the whole thing is deployed to production, or will be soon.

Doing so, you’ll stress on the necessity to keep master stable: developers don’t want to break everything because of its modifications were deployed, so they’re more likely to pay attention about his code stability before merge.

Few comments

This kind of workflow perfectly fits for projects that doesn’t have release nor versions.

You do continuous integration into master and you deploy the stable project to production, sometimes several times a day. You’ll probably never rollback on master.

Thus, you’ll very unlikely add series of big bugs. If problems appears, they’re quickly fixed on the go. There is no difference between a big feature and a small hotfix in terms of process. No matters what kind of change you have to do, the workflow still the same and keeps easy to use.

Useful links

Here again, you might have a look to the original post to go further into explanations.

Technically, GitHub is doing his best so you can deal with this entire workflow directly from your browser. Bitbucket is doing a great job also.

If you ever need, there is also a git extension which helps you to implement the workflow. But I guess you can handle it by yourself, in the browser.

Final words

To choose the best workflow depends on the nature and needs of your project. It’s up to you to consider which of these examples fit more or less with your reality, and adapt a workflow to your needs if so.

These are workflows I typically use so far. If you have other tracks, ideas or comments, please share.

Convert a SASS project into LESS

Tue, 11 Jun 2013 00:00:00 GMT

Matters of taste

LESS and SASS today are the two most popular CSS preprocessors so far.

They are quite similar and give functionalities to CSS that every front-end developer ever dreamt: variables, functions, mathematical operations, selectors nesting, etc.

However, there are some differences:

SASS is compiled with Ruby, it has two different syntaxes: .sass and .scss.
The second one, closer to the CSS syntax, is the most used.
LESS is compiled with Javascript, it has one syntax which is quite close to the CSS.

As a general rule, we can say that SASS is more powerful than LESS because it notably has a bunch of additional functionalities. However, this is a matter of taste and LESS could suffice enough to please you and, in my opinion, is easier to use at first.

Personally, I use LESS instead of SASS with my projects, mostfully because I get used to it.

In the same time, I tend to use the inuit.css framework (instead of Bootstrap) on these projects. But inuit.css uses SASS!

Hopefully, I’m not the only one who likes LESS and Peter Wilson has worked to create the LESS version of the framework. As I was keen on this idea, I joined the project we are maintaining today: the official LESS port of inuit.css.

It’s all about traducing the SASS framework into LESS, which leads us to 3 options:

The SASS code is identical to the LESS one, so it’s the same principle
The SASS code as an equivalent in LESS, so you need to find the alternative
The SASS code doesn’t have any equivalent in LESS and you need to ruse - or ignore it -

Here is a broad overview of these options, as far as I know.

What is identical in LESS

In such a case, it’s dead easy: there is nothing to do.

Indeed, even though they are differents, SASS and LESS both share some basic concepts.

Nesting

One of the guiding principle of CSS preprocessors: selectors nesting.

Instead of creating huge selectors to specify inheritance, you just have to nest them like this:

.islet {
  margin-top: 24px;

  p {
    color: #bada55;
    font-weight: bold;
  }
}

That will produce the following code, in both languages:

.islet {
  margin-top: 24px;
}

.islet p {
  color: #bada55;
  font-weight: bold;
}

Beware - Developers, whether they are experimented or not, often abuse of nesting which bloats their CSS for no valuable reason.

Keep in mind the inception rule: never go farther than 4 nested levels.

Comments and compilation

In addition to features they bring, preprocessors help you to produce code clear and organized while having a single compiled - and compressed - CSS file as the output for production.

In that spirit, SASS and LESS both have alternate comments that are not compiled into CSS. So this code:

/**
 * The date/time
 */
.timeline__time {
  position: absolute;
  display: block;

  // The actual inner width is `25% - x`, `x` is the padding
  padding-right: 24px;
  width: 200px;
}

Will produce the following code:

/**
 * The date/time
 */
.timeline__time {
  position: absolute;
  display: block;

  padding-right: 24px;
  width: 200px;
}

Which could be very helpful in case you want to add some code comments which would not be relevant for production code.

Please note that a compiled file for production should be compressed so it doesn’t have CSS comments neither, excepted if you decide to preserve them. YUI compressor uses /*! */ to preserve CSS comments for instance.

Imports

Preprocessors help you to import other files very easily with @import, which allows you to build a clear and modular architecture of your source files. Dare I say: CSS preprocessors are OOCSS best friends.

A best practice may be to create a main.less / _main.scss file which role is to import the source file you need to produce your final main.css:

/**
 * Setup
 */
@import 'inuit.css/defaults';
@import 'vars';
@import 'inuit.css/inuit';

/**
 * It's all yours, cap’n… Begin importing your stuff here.
 */
@import 'ui/base';
@import 'ui/layout';

@import 'ui/mod-block-list';
@import 'ui/mod-helper';

/* etc. */

You’ll note here that it’s pointless to add the extension, whatever preprocessor you use.

Beware - All likeness taken after, the @import command of preprocessors has nothing to do with CSS one. Indeed, preprocessors will import your files when you compile them to output a unique CSS file that will be used in production. But CSS import will load many files by the browser.

Please note that the use of @import is not a very good CSS practice, try to avoid it.

What has an equivalent in LESS

In such a case, you mainly have to know the syntax and specificities of each language as fundamentals principles are the same. Let’s see what you’ve got…

Variables

SASS and LESS both allow you to create variables, which is basically the Holy Grail in CSS!

The concept is very straight forward. The only difference here is that SASS uses $ while LESS uses @.

/* With SASS */
$color: #bada55;

.header {
  color: $color;
}

/* With LESS */
@color: #bada55;

.header {
  color: @color;
}

And so the CSS output is:

.header {
  color: #bada55;
}

Mixins

SASS and LESS both allow you to create what we call mixins. That means that you could simply create groups of properties that can be quickly included wherever you want to.

Here again, the main difference is the syntax, not the concept:

/* With SASS */
@mixin bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

.header {
  @include bordered;
}

/* With LESS */
.bordered() {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

.header {
  .bordered();
}

This will output:

.header {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

You should know that mixins can do more and have parameters, default values, conditions, etc.

Without going further into details, you should know also that mixins can take a variable number of arguments into account.

However, while SASS deals perfectly with the different values you give to the parameters, you would have to escape those you pass to LESS if you don’t want him to interpret the whole thing as a single big variable.

Escaping in LESS would return the exactly given output thanks to ~“my string”, which could be helpful for a bunch of tips.

Technically, code is the following:

/* With SASS */
@mixin box-shadow($shadows…) {
  -moz-box-shadow: $shadows;
  -webkit-box-shadow: $shadows;
  box-shadow: $shadows;
}

.shadows {
  @include box-shadow(0 4px 5px #666, 2px 6px 10px #999);
}

/* With LESS */
.box-shadow(@shadows…) {
  -moz-box-shadow: @shadows;
  -webkit-box-shadow: @shadows;
  box-shadow: @shadows;
}

.shadows {
  .box-shadow(~'0 4px 5px #666, 2px 6px 10px #999');
}

And that would produce this CSS:

.shadows {
  -moz-box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
  -webkit-box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
  box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
}

Excepted some little specificities, mixins just work the same.

Operations

Every preprocessor has is bunch of mathematical operations which could be very useful to do some flexible styling with variables.

Syntaxes are very close and intuitive - just a matter of + and -, etc. A best practice is to isolate these operations into parenthesis so you avoid potential confusions and conflicts.

However, you should know that LESS is considering the first unit specified in the calculus, which could lead to some aberrations while SASS will properly output a warning instead of compiling something wrong:

.container {
  width: 300px + 2em; // == 302px o_O
}

So in LESS you should better not specify variables unit so you don’t have that kind of nasty surprises when you do operations. You just have to apply the unit at the very end and you’re all set:

@base-font-size: 16;
@base-spacing-unit: 24;

html {
  font-size: (@base-font-size/16)*1em;
  margin-bottom: @base-spacing-unit*1px;
}

Which will produce:

html {
  font-size: 1em;
  margin-bottom: 24px;
}

Functions

Each preprocessor brings their own functions that allow you to do a bunch of very nice things with colors, maths, strings, etc.

You may have a look to each respective list to get an idea:

Interpolation

Sometimes you’ll need to include some variables into stings and interprate them however. That’s what we call interpolation and both SASS and LESS allow you to do that:

/* With SASS */
$base-url: '../images';

.container {
  background-image: url('#{$base-url}/bg.png');
}

/* With LESS */
@base-url: '../images';

.container {
  background-image: url('@{base-url}/bg.png');
}

Which will produce:

.container {
  background-image: url('../images/bg.png');
}

The only difference is the syntax: #{ $var } with SASS and @{ var } with LESS.

You also can interpolate variables within selectors as we could see with loops - yep, I’m working on my transitions.

Loops

Technically speaking, both preprocessors can implement loops which could be very useful.

However, SASS natively deals with the iteration logic, not LESS. In fact, you can use an alternative based on mixins to create the loop behavior with LESS.

With LESS, here is the deal:

Create a mixin with an @index parameter
The mixin will produce the content of the loop while @index > 0
At the end of the mixin, you decrease @index
You create an empty verion of the mixin to stop the loop when @index = 0

Which leads us to the following syntaxes for a loop:

/* With SASS */
$index: 5;

@while $index > 0 {
  // Interpolate the class name
  .container-#{$index} {
    z-index: $index;
  }

  // Decrease the index
  $index: $index - 1;
}

/* With LESS */
.loop (@index) when (@index > 0) {
  // Interpolate the class name
  .container-@{index} {
    z-index: @index;
  }

  // Decrease the index and start the loop again
  .loop (@index - 1);
}

// Stop the loop at 0
.loop (0) {
}

// Start the loop
.loop (5);

Which will output, once compiled:

.container-5 {
  z-index: 5;
}
.container-4 {
  z-index: 4;
}
.container-3 {
  z-index: 3;
}
.container-2 {
  z-index: 2;
}
.container-1 {
  z-index: 1;
}

This technique is used by Bootstrap to generate spans regarding the number of columns.

Extend and silent classes

With SASS you can extend a class properties very easily to share a common style, the second class inherits style of the first one.

For instance, this:

.error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error {
  @extend .error;
  border-width: 3px;
}

Will give the following code:

.error,
.serious-error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error {
  border-width: 3px;
}

SASS can create what we call silent classes: you just define classes that wouldn’t be compiled until they are included somewhere with @extend.

So this code:

a%error {
  color: red;
  font-weight: bold;
}

.notice {
  @extend %error;
}

Will output the following:

a.notice {
  color: red;
  font-weight: bold;
}

With LESS, you’ll generally use mixins to realize that kind of extensions. Just like a silent class, the mixin won’t be compiled until it’s included somewhere. So it comes with the same spirit, only the syntax changes:

.error() {
  a& {
    color: red;
    font-weight: bold;
  }
}

.notice {
  .error();
}

That said, you’ll note that SASS is extending smartly selectors - .error, serious-error in the previous example. With LESS, you’d need to do that by hand.

Note - LESS v1.4 - which is currently in beta - will introduce :extend() that could handle selectors extension. The syntax would be closer to the CSS one, just like a pseudo-selector, which should produce something like that:

.error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error:extend(.error) {
  border-width: 3px;
}

`!default` variables

With SASS you can set a default value to variables at any time. The default value is used if the variable is not already defined somewhere.

$base-font-size: 14px;
$base-font-size: 16px !default;
$base-spacing-unit: 24px !default;

.container {
  font-size: $base-font-size;
  margin-bottom: $base-spacing-unit;
}

.container {
  font-size: 16px;
  margin-bottom: 24px;
}

This technique is very useful because you can define defaults into the core of the module you’re developing, so you allow users to override them if necessary from the outside.

Need a concrete example? I’ve got that: the framework core of inuit.css use a bunch of defaults so the developer can use the framework as a submodule: he can update it but he never has to touch it, never!

To override a variable, he just needs to define it in its own configuration file:

.
|-- inuit.css/ # Framework core
| |-- base/
| |-- generic/
| |-- objects/
| |-- \_defaults.scss # Default variables
| |-- \_inuit.scss # Setup file for inuit.css
|
|-- ui/
|-- \_vars.scss # Specific variables
|-- main.scss # Setup file for the project

So he can override variables in _vars.scss and organize main.scss as follows:

/**
 * Setup
 */
@import 'vars';
@import 'inuit.css/inuit';

Without touching anything from the inuit.css core he is able to configure it entirely.

The fact is, you ain’t gonna need this with LESS.

Thanks Chris Snyder for pointing this out!

For a long time I thought LESS didn’t provide the ability to do the same, and I’ve had to find hacks to this problem.

Actually, variables work differently in LESS since the pre-processor uses lazy loading. That means variables can be used before being described.

Hence, you can perfectly override variables later in your codebase. Which is the equivalent of having default variables:

@base-font-size: 14px;
@base-spacing-unit: 24px;

.container {
  font-size: @base-font-size;
  margin-bottom: @base-spacing-unit;
}

/* … later in your code */
@base-font-size: 16px;

Will produce the same result:

.container {
  font-size: 16px;
  margin-bottom: 24px;
}

Hence, we could do the same with inuit.css and use proper (default) variables in the framework while giving the capacity to developers to override them after.

/**
 * Setup
 */
@import 'inuit.css/inuit';
@import 'vars';

What couldn’t be reproduced in LESS

Here is a non-exhaustive list of what SASS is able to do and not LESS, without any real alternative but ingenious hacks.

Block of content within a mixin

If you are using SASS, you can pass a whole block of content into a mixin thanks to the @content variable. Concretely, this:

@mixin apply-to-ie6-only {
  html {
    @content;
  }
}

@include apply-to-ie6-only {
  #logo {
    background-image: url(/logo.gif);
  }
}

Will compile into:

html #logo {
  background-image: url(/logo.gif);
}

As far as I know, there is no possibility to do that in LESS - but I’d consider any suggestion!

Variable properties

With SASS you also can use interpolation to have variable properties. This is extremely useful to create powerful mixins like this:

@mixin border-badass($side) {
  border-#{$side}: 1px #bada55 solid;
}

.container {
  @include border-badass(left);
}

Will output:

.container {
  border-left: 1px #bada55 solid;
}

However, you need to do a mixin per property in LESS, which is very painfull. So you may need to get use of it…

…

… well, in fact, there IS a kind of weird hack that can produce the same result. I deny any responsibility for its weirdness, you are smart enough to decide whether or not it worth using it!

The thing is that browsers will ignore unknown CSS properties.

So let’s say, hack: 1; would’n be very valid right? But it wouldn’t be considered. If you keep that in mind and use LESS interpolation over properties values, you’d be able to imagine the following code:

.border-badass(@side) {
    hack: 1 ~"; border-@{side}: 1px #BADA55 solid";
}

.container {
    .border-badass(left);
}

Which will output:

.container {
  hack: 1;
  border-left: 1px #bada55 solid;
}

Technically, it works.

I don’t tell you to use it, but we can imagine that you automatically treat your compiled CSS so you delete every hack:1; for instance. We can also imagine that LESS will have this feature later.

So keep in mind: it’s weird, but it works though…

Final words

Here we are! That was my 50 cents about main similarities and differencies I experimented between SASS and LESS. To convert a SASS project into LESS isn’t that difficult, but you need do take care of each language specificities.

From an objective point of view, SASS is more powerful than LESS and has real programming notions inside. However, its syntax and spirit is even more far from the original CSS compared to LESS, in my humble opinion.

It’s much more a question of habit and comfort. What counts is that you’re using a CSS preprocessor to simplify development and make your stylesheets easier to scale and maintain: the future you will thank the present you for that!

For those who would like to play with it online, here you go:

Sass-try, for SASS
Less2css, for LESS

If you have any suggestion, spot any mistake or have some comments to do on this (long) post, please do.

Plop!

Convertir un projet SASS en LESS

Sun, 09 Jun 2013 00:00:00 GMT

Les goûts et les couleurs

LESS et SASS sont aujourd’hui les deux pré-processeurs CSS les plus populaires, et de loin.

Tous deux sont assez similaires et apportent au CSS les fonctionnalités dont rêvent basiquement tout développeur front-end, à savoir : variables, fonctions, opérations mathématiques, imbrication des sélecteurs, etc.

Cependant, leur nature diffère quelque peu :

SASS est compilé en Ruby, il présente deux syntaxes différentes : .sass et .scss.
La seconde, plus proche de celle du CSS, est la plus utilisée.
LESS est compilé en Javascript, il présente une syntaxe assez proche du CSS.

D’une manière générale, on constate que SASS est plus puissant que LESS car il dispose notamment d’un certain nombre de fonctionnalités supplémentaires. Toutefois, les goûts et les couleurs étant ce qu’ils sont, LESS peut tout à fait suffir à vous contenter car il est bien suffisant et, selon moi, un peu plus facile à prendre en main au début (puis l’habitude fait le reste).

Personnellement, j’utilise LESS plutôt que SASS sur mes projets, par habitude probablement.
Dans le même temps, j’ai tendance à utiliser le framework inuit.css (plutôt que Bootstrap) sur ces projets. Mais inuit.css, c’est du SASS !

Fort heureusement, je ne suis pas le seul à aimer LESS et Peter Wilson s’est efforcé de mettre en place la version LESS du framework. Emballé par l’idée, j’ai rejoint son projet et je maintient aujourd’hui le port LESS officiel de inuit.css.

Le principe consiste donc à traduire le framework SASS en LESS, ce qui conduit à 3 éventualités :

Le code SASS est identique au code LESS, c’est le même principe
Le code SASS a un équivalent en LESS, il faut alors trouver l’alternative
Le code SASS n’a pas d’équivalent en LESS et il faut savoir ruser (ou fermer les yeux)

Voici donc un petit tour sur ces cas de figures, d’après ce que j’ai pu en expérimenter.

Ce qui est identique en LESS

Dans ce cas, c’est peinard : il n’y a pas grand chose à faire.

En effet, malgré leurs différences, SASS et LESS partagent quelques concepts fondamentaux.

Imbrication (nesting)

L’un des principes phares du pré-processeur CSS : l’imbrication des sélecteurs.

Plutôt que de créer des sélecteurs à rallonge afin de spécifier l’héritage, il suffit d’imbriquer les sélecteurs les uns dans les autres. Ainsi, ceci :

.islet {
  margin-top: 24px;

  p {
    color: #bada55;
    font-weight: bold;
  }
}

Produira le code suivant, dans les deux langages :

.islet {
  margin-top: 24px;
}

.islet p {
  color: #bada55;
  font-weight: bold;
}

Attention - Il arrive souvent que les développeurs, expérimentés ou non, s’emportent avec l’imbrication et en abusent plus que de raison, ce qui a tendance à alourdir inutilement le CSS, un vrai cauchemard !

Gardez donc en tête la règle de l’inception : ne jamais aller au delà de 4 niveau d’imbrication.

Commentaires et compilation

Outre les fonctionnalités qu’ils apportent, les pré-processeurs permettent de disposer d’un code source clair et organisé, tout en produisant un seul fichier CSS compilé (et compressé) pour la production.

Dans cet état d’esprit, SASS et LESS proposent tous deux des commentaires alternatifs qui ne sont pas conservés lors de la compilation. Ainsi donc, ceci :

/**
 * The date/time
 */
.timeline__time {
  position: absolute;
  display: block;

  // The actual inner width is `25% - x`, `x` is the padding
  padding-right: 24px;
  width: 200px;
}

Produira le code suivant :

/**
 * The date/time
 */
.timeline__time {
  position: absolute;
  display: block;

  padding-right: 24px;
  width: 200px;
}

Ce qui peut être assez pratique pour placer des commentaires qui n’ont aucune pertinence dans le code compilé, mais ont un sens vis-à-vis du code source.

Notez cependant qu’un fichier compilé en production sera préférentiellement compressé de manière à ne pas inclure les commentaires CSS, à moins de les préserver explicitement (avec /*! */ en utilisant YUI compressor, par exemple).

Imports

Les pré-processeurs permettent également d’importer très simplement d’autres fichiers grâce à @import, ce qui permet la mise en place d’une architecture claire et modulaire des fichiers sources. Oui, les pré-processeurs CSS sont les grands amis de l’OOCSS.

Une bonne pratique consiste donc à créer un fichier principal main.less / _main.scss dont le rôle est d’importer les fichiers dont vous aurez besoin pour produire le fichier final main.css :

/**
 * Setup
 */
@import 'inuit.css/defaults';
@import 'vars';
@import 'inuit.css/inuit';

/**
 * It's all yours, cap’n… Begin importing your stuff here.
 */
@import 'ui/base';
@import 'ui/layout';

@import 'ui/mod-block-list';
@import 'ui/mod-helper';

/* etc. */

Vous noterez que préciser l’extension n’est pas utile, que ce soit en SASS ou en LESS.

Attention - Malgré toute ressemblance, la commande @import des pré-processeurs n’a rien à voir avec celle de CSS. En effet, le pré-processeur va importer vos fichiers lors de la compilation afin de produire un fichier CSS unique tandis que l’import en CSS fera télécharger plusieurs fichiers par le navigateur.

Notez également que l’utilisation de @import est une mauvaise pratique CSS, à éviter donc.

Ce qui a un équivalent en LESS

Dans ce cas, il s’agit surtout de connaître la syntaxe et les spécificités de chaque langage, les principes fondamentaux étant les mêmes. Voyons donc ce que nous avons…

Variables

SASS comme LESS donnent la possibilité de créer des variables. Et les variables en CSS, c’est quasiment le Saint Graal !

Le concept est assez simple à assimiler, la seule différence entre les deux c’est que SASS utilise des $ tandis que LESS utilise des @. Les goûts et les couleurs…

/* Avec SASS */
$color: #bada55;

.header {
  color: $color;
}

/* Avec LESS */
@color: #bada55;

.header {
  color: @color;
}

Le rendu CSS :

.header {
  color: #bada55;
}

Mixins

SASS et LESS permettent de créer ce qu’on appelle des mixins.

Ce mot barbare signifie tout simplement qu’il est possible de créer des groupes de propriétés pouvant être inclus très simplement ailleurs.

Là encore, c’est surtout la syntaxe qui diffère, le principe est le même :

/* En SASS */
@mixin bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

.header {
  @include bordered;
}

/* En LESS */
.bordered() {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

.header {
  .bordered();
}

Ce qui donnera en CSS :

.header {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

Il est à savoir que les mixins vont plus loin que ça et peuvent prendre en compte des paramètres, des valeurs par défaut, des conditions, etc.

Sans rentrer dans les détails, sachez par exemple que les mixins peuvent prendre en compte un nombre d’arguments variables.

Cependant, là où SASS gère parfaitement les différentes valeurs distinctes passées en paramètre, il faut échapper celles de LESS si on veut qu’il n’interprète pas le tout comme une seule grosse variable (qu’il prenne en compte la virgule quoi).

L’échappement en LESS permet tout simplement de retourner une chaîne de caractère telle quelle grâce à ~“ma chaîne”, ce qui servira dans un certain nombre d’astuces (du coup).

Techniquement cela se présente comme ceci :

/* En SASS */
@mixin box-shadow($shadows…) {
  -moz-box-shadow: $shadows;
  -webkit-box-shadow: $shadows;
  box-shadow: $shadows;
}

.shadows {
  @include box-shadow(0 4px 5px #666, 2px 6px 10px #999);
}

/* En LESS */
.box-shadow(@shadows…) {
  -moz-box-shadow: @shadows;
  -webkit-box-shadow: @shadows;
  box-shadow: @shadows;
}

.shadows {
  .box-shadow(~'0 4px 5px #666, 2px 6px 10px #999');
}

Ce qui donnera en CSS :

.shadows {
  -moz-box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
  -webkit-box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
  box-shadow: 0 4px 5px #666, 2px 6px 10px #999;
}

Outre les petites spécificités, les mixins fonctionnent de la même manière.

Opérations

Chaque pré-processeur apporte son lot d’opérations mathématiques, très utiles pour réaliser un certain nombre de calculs et d’ajustements qui ne dépendront que de quelques variables, modifiables à souhait.

Les syntaxes sont similaires et assez intuitives (des histoires de +, de -, etc.). Une bonne pratique consiste à isoler les opérations entre parenthèses afin d’éviter les confusions et potentiels conflits.

Cependant, il faut savoir que LESS considère la première unité spécifiée dans le calcul, ce qui peut conduire à des aberrations (SASS lui ne compilera pas et vous sortira un joli warning) :

.container {
  width: 300px + 2em; // == 302px o_O
}

En LESS il est donc préférable de ne pas spécifier les unités des variables afin de ne pas avoir de mauvaises surprises lors des opérations mathématiques. Il suffit de prendre l’habitude d’appliquer l’unité à la fin, lors de son affectation à une propriété :

@base-font-size: 16;
@base-spacing-unit: 24;

html {
  font-size: (@base-font-size/16)*1em;
  margin-bottom: @base-spacing-unit*1px;
}

Ce qui donnera :

html {
  font-size: 1em;
  margin-bottom: 24px;
}

Fonctions

Chaque pré-processeur vient avec son lot de fonctions qui permettent de faire un certain nombre de trucs très sympa comme transformer les couleurs, faire des maths, manipuler des chaînes de caractères, etc.

Le plus simple, c’est de vous donner les liens vers les listes exhaustives de chacun :

Interpolation

Parfois, il est nécessaire d’inclure des variables au sein de chaines de caractères et de les interpréter tout de même. C’est ce qu’on appelle l’interpolation et SASS comme LESS permettent cela :

/* Avec SASS */
$base-url: '../images';

.container {
  background-image: url('#{$base-url}/bg.png');
}

/* Avec LESS */
@base-url: '../images';

.container {
  background-image: url('@{base-url}/bg.png');
}

Ce qui donnera :

.container {
  background-image: url('../images/bg.png');
}

Seule la syntaxe diffère, #{ $var } pour SASS et @{ var } pour LESS.

Il est également possible d’interpoler des variables dans les sélecteurs, comme nous allons le voir avec les boucles (oui, je travaille mes transitions).

Boucles

Techniquement parlant, les deux pré-processeurs permettent de créer des boucles, ce qui peut s’avérer assez utile parfois.

En revanche, si SASS gère nativement la logique de l’itération, LESS n’a rien de tel. En fait, il s’agit véritablement d’une alternative qui consiste à se baser sur les mixins afin de créer le comportement de la boucle.

En LESS, le principe est donc le suivant :

On crée un mixin se basant sur un @index
Le mixin produit le contenu de la boucle tant que @index > 0
A la fin du mixin, on décrémente @index
On crée une variante vide du mixin pour arrêter la boucle quand @index = 0

Ce qui nous donne les syntaxes suivantes :

/* En SASS */
$index: 5;

@while $index > 0 {
  // On interpole le nom de la classe
  .container-#{$index} {
    z-index: $index;
  }

  // On décrémente l'index
  $index: $index - 1;
}

/* En LESS */
.loop (@index) when (@index > 0) {
  // On interpole le nom de la classe
  .container-@{index} {
    z-index: @index;
  }

  // Relance la boucle en décrémentant l'index
  .loop (@index - 1);
}

// Arrête la boucle à 0
.loop (0) {
}

// Lance la boucle (le mixin)
.loop (5);

Ce qui donnera, une fois compilé :

.container-5 {
  z-index: 5;
}
.container-4 {
  z-index: 4;
}
.container-3 {
  z-index: 3;
}
.container-2 {
  z-index: 2;
}
.container-1 {
  z-index: 1;
}

Cette technique est notamment utilisée par Bootstrap pour générer leurs spans en fonction du nombre de colonnes.

Extensions et classes silencieuses

En SASS, il est possible d’étendre les propriétés d’une classe à une autre afin de partager un style commun, la seconde classe héritant de la première.

Par exemple, ceci :

.error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error {
  @extend .error;
  border-width: 3px;
}

Donnera le code suivant :

.error,
.serious-error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error {
  border-width: 3px;
}

SASS permet également de créer ce que l’on appelle des classes silencieuses : il s’agit de définir des classes qui ne seront pas compilées avant d’être explicitement incluses avec @extend.

Ainsi, ceci :

a%error {
  color: red;
  font-weight: bold;
}

.notice {
  @extend %error;
}

Produira le code suivant :

a.notice {
  color: red;
  font-weight: bold;
}

En LESS, on utilise généralement les mixins pour réaliser ce genre d’extension. Selon le même principe que la classe silencieuse, le mixin ne sera pas compilé tant qu’il n’aura pas été inclus quelque part. Le principe est donc sensiblement le même, seule la syntaxe diffère :

.error() {
  a& {
    color: red;
    font-weight: bold;
  }
}

.notice {
  .error();
}

Cela étant, vous noterez que SASS gère intelligemment l’extension en synthétisant les sélecteurs (.error, serious-error dans l’exemple précédent). En LESS, il faudrait le faire à la main.

Note - La version 1.4 de LESS (actuellement en béta) introduit :extend() qui permettra de gérer les extensions au niveau des sélecteurs. La syntaxe sera donc plus proche du CSS, rappelant celle des pseudo-sélecteurs, ce qui devrait donner quelque chose du genre :

.error {
  border: 1px #f00;
  background-color: #fdd;
}

.serious-error:extend(.error) {
  border-width: 3px;
}

Variables `!default`

Avec SASS, il est possible de donner une valeur par défaut aux variables, a posteriori. Cela signifie que la valeur sera affectée si et seulement si la variable n’est pas déjà définie.

$base-font-size: 14px;
$base-font-size: 16px !default;
$base-spacing-unit: 24px !default;

.container {
  font-size: $base-font-size;
  margin-bottom: $base-spacing-unit;
}

.container {
  font-size: 16px;
  margin-bottom: 24px;
}

L’intérêt de cette technique, c’est de pouvoir définir des variables par défaut au coeur du module développé, tout en permettant à celles-ci d’être redéfinies de l’extérieur.

Un exemple concret ? Le coeur du framework d’inuit.css utilise un ensemble de variables par défaut, permettant au développeur d’utiliser ce dernier comme un sous-module : il le met éventuellement à jour mais ne touche jamais au code qu’il y a dedans.

Pour modifier une variable, il doit simplement la redéfinir plus haut, dans son propre fichier de configuration :

.
|-- inuit.css/ # Coeur du framework
| |-- base/
| |-- generic/
| |-- objects/
| |-- _defaults.scss # Variables par défaut
| |-- _inuit.scss # Fichier setup inuit.css
|
|-- ui/
|-- _vars.scss # Variables spécifiques
|-- main.scss # Fichier setup projet

Il lui suffit de surcharger éventuellement des variables dans _vars.scss et d’organiser son main.scss ainsi :

/**
 * Setup
 */
@import 'vars';
@import 'inuit.css/inuit';

Sans toucher au code de inuit.css, il est donc capable de le configurer entièrement.

En vérité, vous n’avez pas besoin de cette fonctionnalité en LESS.

Merci Chris Snyder de m’avoir fait remarqué ce point !

Pendant un bon moment je pensais que LESS ne proposait pas d’équivalent aux variables par défaut de SASS, et qu’il fallait trouver d’habiles hacks pour contourner le problème.

En réalité, les variables fonctionnent différement avec LESS car le pré-processeur fait du lazy loading. Ce qui signifie que les variables peuvent être utilisées avant d’être définies.

Ainsi, vous pouvez parfaitement surcharger les variables plus tard dans votre code. Ce qui est équivalent à avoir des variables par défaut :

@base-font-size: 14px;
@base-spacing-unit: 24px;

.container {
  font-size: @base-font-size;
  margin-bottom: @base-spacing-unit;
}

/* … plus loin dans le code */
@base-font-size: 16px;

Donnera le même résultat :

.container {
  font-size: 16px;
  margin-bottom: 24px;
}

De cette façon, nous pouvons faire la même chose avec inuit.css et tranquillement utiliser des variables (par défaut) dans le framework tout en laissant la possibilité aux développeurs de les surcharger ensuite.

/**
 * Setup
 */
@import 'inuit.css/inuit';
@import 'vars';

Ce qui ne peut être reproduit en LESS

Voici donc une liste non exhaustive de ce dont SASS est capable sans qu’il n’existe de véritable alternative en LESS (éventuellement des ruses de sioux).

Bloc de contenu dans un mixin

Avec SASS il est possible de passer tout un bloc de contenu au sein d’un mixin avec la variable @content. Concrètement, ceci :

@mixin apply-to-ie6-only {
  *html {
    @content;
  }
}

@include apply-to-ie6-only {
  #logo {
    background-image: url(/logo.gif);
  }
}

Se compile ainsi :

*html #logo {
  background-image: url(/logo.gif);
}

D’autant que je sache, il n’existe pas d’équivalent en LESS (désolé).

Variabiliser les propriétés

En SASS, il est également possible d’utiliser l’interpolation pour variabiliser une propriété. C’est extrêmement utile pour créer des mixins concis et puissants. Ainsi, ceci :

@mixin border-badass($side) {
  border-#{$side}: 1px #bada55 solid;
}

.container {
  @include border-badass(left);
}

Donnera par exemple :

.container {
  border-left: 1px #bada55 solid;
}

En LESS en revanche, il s’agira de faire un mixin par propriété, ce qui complique énormément la tâche pour ce genre de cas de figure. Il faut donc apprendre à s’en passer…

…

… bon, en réalité, il existe une bidouille qui permet d’obtenir le même résultat, mais qui n’a rien de très propre. A utiliser en votre âme et conscience donc !

Le principe se base sur le fait que les navigateurs ignorent les propriétés inconnues en CSS.

Ainsi, hack: 1; ne sera pas très valide, mais ne sera pas considéré. Sachant cela, et en le combinant avec l’interpolation LESS qui peut se faire sur les valeurs, on peut imaginer le code suivant :

.border-badass(@side) {
  hack: 1 ~'; border-@{side}: 1px #BADA55 solid';
}

.container {
  .border-badass(left);
}

Qui donnera :

.container {
  hack: 1;
  border-left: 1px #bada55 solid;
}

Techniquement, ça marche.

De là à l’utiliser, tout dépend de votre besoin je dirais. On peut imaginer que vous traitiez automatiquement votre CSS compilé lors du build pour supprimer les occurrences à hack:1; par exemple. On peut aussi imaginer que LESS intègrera cette fonctionnalité à l’avenir.

Sinon, gardez en tête que c’est un peu sale (quand même).

Pour finir

Voici donc les principales similarités et différences qui existent entre SASS et LESS, d’après mon expérience. Convertir un projet SASS en LESS n’a rien de bien sorcier en soit, à condition de connaître et prendre garde aux spécificités de chaque langage.

D’un point de vue objectif, SASS est plus puissant que LESS et dispose de véritables notions de programmation qui peuvent en séduire plus d’un. Cependant, sa syntaxe et son esprit s’éloignent d’autant, LESS étant plus “naturel” et proche du langage CSS selon moi.

C’est donc plutôt une question de préférence et de confort que vous aurez à faire dans la plupart des cas. Le principal, c’est d’avoir fait le pas et d’utiliser un pré-processeur pour simplifier le développement et faciliter la maintenance de votre CSS : vous vous direz merci tôt ou tard !

Pour ceux qui veulent jouer et tester tout ceci en ligne, voici :

Sass-try, pour le SASS
Less2css, pour le LESS

Si vous voyez des ajouts, des erreurs ou avez des remarques à émettre sur ce post, n’hésitez pas.

Plop !

Faire un blog multilingue avec Jekyll

Wed, 29 May 2013 00:00:00 GMT

Note sur la compatibilité

Ce qui suit se base sur l’utilisation de Jekyll v0.12.1.

Pour Jekyll v1.5, allez jeter un oeil à celui d’Avril 2014.

Veuillez noter que des changements majeurs sont survenus lors du passage à la v1.0.0, rendant certaines de ces astuces non compatibles (je pense surtout aux plugins). Je rédigerai un nouvel article lorsque je mettrais à jour mon propre Jekyll à une version v1.0+.

Si vous le souhaitez, vous pouvez toujours installer une ancienne version de Jekyll avec la commande suivante :

# Installe l'ancienne version de jekyll
$ sudo gem install jekyll --version 0.12.1

# Désinstalle la version actuelle si vous l'avez téléchargée
$ sudo gem uninstall jekyll --version <your current version>

Petit retour sur Jekyll

J’ai commencé ce blog avec un article présentant Jekyll et ce qui m’avait amené à ce choix.

Pour résumer l’intérêt de ce “générateur de site dynamique” par rapport à un CMS tout prêt tel que Wordpress, j’avais avancé les points suivants :

Pas besoin/envie de m’embêter avec une BDD. Restons simple et faisons du front-end.
Pouvoir mettre mon site à jour quand je push sur Github. J’aurais évidemment pu mettre en place des hooks pour reproduire le même comportement sur un serveur, mais c’est totalement inutile grâce à Jekyll et Github Pages.
Suivre les dernières tendances en matière de développement web. L’expérience Jekyll me paraissait donc tentante, j’ai succombé.

Simplement, Jekyll est adapté pour du blogging… mais du blogging en anglais (et voui). Par défaut, il n’est donc pas vraiment optimisé pour le français et encore moins pour créer un blog multilingue.

Bien entendu, c’est tout à fait possible si l’on sait ruser et mettre un peu les mains dans le cambouis. Je me propose donc ici de vous expliquer les quelques étapes dont vous aurez besoin si vous souhaitez pouvoir blogger dans 2 langues, ou plus.

Do you parler Français ?

Le meilleur exemple de la nature english oriented de Jekyll est certainement le filtre Liquid date. Ce dernier permet de retourner très simplement la date de publication d’un post, par exemple, mais dans le format anglais ! Certes, si vous vous contentez des chiffres ça passera sans problème. En revanche ça risque de faire tâche d’avoir des 19 April, 2013 qui trainent un peu partout sur votre blog francophone.

Le deuxième soucis majeur se pose lorsque vous souhaitez distinguer les articles en fonction de leur langue, pour proposer 2 pages d’index différentes par exemple. La bonne idée qui vous vient, c’est naturellement de créer une catégorie par langue. Mais le paginator Jekyll, qui vous permet d’afficher le listing paginé des posts de votre site, n’a pas été créé pour gérer les catégories. Cela pose un léger soucis puisque vous allez vous retrouver à choisir entre :

Tous les posts d’une catégorie, listés sur une seule page
Un listing de X posts par page, toutes catégories (langues) confondues

Bref, autant d’obstacles qui pimentent un peu le challenge. Voyons comment s’en sortir malgré tout.

Parlons stratégie

Prenons le problème à l’envers, et définissons ce que nous souhaitons obtenir pour commencer :

Nous voulons que l’anglais soit la langue par défaut, à la racine de projet.
Chaque langue représente une catégorie, ce qui peut être aisément retranscrit avec l’architecture des dossiers.
La partie française doit être accessible à partir de l’URL de base /fr (ce qui se goupille pas trop mal avec les précédentes considérations).
Les articles en anglais doivent être listés uniquement sur index.html
Les articles en français doivent être listés uniquement sur index.html/fr
La pagination doit gérer la distinction anglais/français.
Ca doit rester simple !

Élaborons donc l’architecture de nos fichiers source d’après ce que nous venons de dire :

.
|-- _includes/ # Bouts de codes inclus ailleurs
|-- _layouts/ # Templates du site
|-- _plugins/ # Plugins pour surcharger de Jekyll
|-- assets/ # LESS/CSS, JS, images, …
|-- fr/ # Categorie FR
| |-- _posts/ # Articles en français
| |-- index.html # Pages html en français
| |-- about.html
| |-- (…)
|
|-- en/ # Catégorie EN
| |-- _posts/ # Articles en anglais
|
|-- index.html # Pages html par défaut (EN)
|-- about.html
|-- (…)
|-- _config.yml # Fichier de configuration de Jekyll

Lorsqu’il est lancé, Jekyll génère le site statique final dans le dossier _site/.

Note - Personnellement, j’utilise le fichier _config.yml pour y mettre des variables qui dépendent de la langue et que je réutilise dans les templates.

Ce n’est pas la solution la plus propre selon moi, mais c’est assez facile à mettre en place et cela fonctionne plutôt bien pour le moment (tant qu’il n’y en a pas trop). Cela changera à l’avenir lorsque je me serais penché sur une manière plus élégante pour faire ça.

Les plugins en renfort

Pour résoudre les problèmes que nous avons soulevé plus tôt, j’ai mis en place 2 petits plugins qui vont surcharger le workflow classique de Jekyll pour le plier à notre volonté (c’est qui l’patron ?).

1. Pagination par categorie

category_pagination.rb modifie le fonctionnement du paginator afin de prendre seulement en compte les articles qui correspondent à la catégorie spécifiée, et ainsi pouvoir distinguer les deux.

J’ai modifié le plugin original afin de définir l’anglais comme catégorie par défaut à la racine au lien d’afficher tous les site.posts.

2. Filtre i18n

i18n_filter.rb customise le traitement de page.date en fonction de la langue.

J’ai du ajouter un fichier _locales/fr.yml afin de créer la fonction localize. Elle fonctionne de la même manière que date mais renvoie le format français de la date.

Le point Github

Les plugins sont installés, les templates sont élaborés, le design est mis en place, le git flow est prêt ainsi que le dépôt sur Github… Pushons joyeusement !

Je constate que la redirection DNS de mon domaine perso fonctionne à merveille mais… erf. Le résultat n’est vraiment pas celui attendu !

Yep, pour ceux qui l’auraient remarqué tout comme moi à ce moment là, Github lance Jekyll en mode --safe, ce qui veut dire que les plugins sont désactivés.

Au revoir pagination par catégorie et filtre i18n.

A chaque problème, sa solution …

… et Google votre meilleur ami.

J’ai pu trouver l’inspiration pour redéfinir mon workflow git et contourner ce nouveau problème en ce qui me concerne. C’est ce que je vous propose très concrètement ci-dessous.

Un petit retour sur le workflow et les branches

Nous allons considérer que notre workflow comporte 2 branches distinctes :

La branche master, qui correspond au site final compilé. Il est généré par Jekyll dans le dossier _site/ lors de la compilation et Github peut très bien héberger directement un site statique avec l’ajout d’un fichier .nojekyll.
La branche develop, qui correspond aux fichiers sources puisque nous avons besoin de les versionner. Ces fichiers seront compilés par Jekyll lors du déploiement, afin de commiter le rendu sur la branche master.

Il n’y a pas de merge de develop dans master avec ce workflow. Il s’agit de deux branches évoluant en parallèle avec une version source du code pour l’une, et compilée pour l’autre.

Le déploiement consiste à compiler le code source de la branche de développement (develop) et à venir committer ces changements sur la branche de production (master).

Deux branches parallèles WTF ?

Bien que cela sorte de la vision classique des branchements aka “tout le modèle de branches part d’un ancêtre commun”, Git permet également de créer de nouvelles branches n’ayant pas d’ancêtre commun avec le commit sur lequel nous nous trouvons. Un peu comme un nouveau projet dans le projet.

C’est ce que l’on appelle des branches orphelines.

Pour créer une telle branche, c’est très simple :

$ git checkout --orphan <new branch>

Dans notre cas, considérons donc que notre branche initiale (par défaut) soit develop. Il s’agit donc de créer une branche master depuis cette branche afin d’y versionner la version compilée de notre site :

$ git checkout --orphan master

Il suffit donc de considérer cette branche comme une version alternative de votre code.

Supprimez tout ce qui n’a rien à y faire (les fichiers sources) et faîtes en sorte d’y versionner le code final, compilé (celui qui se trouve normalement dans le répertoire _site/ du code source).

En ce qui me concerne, j’avais déjà pushé les premiers commits quand je me suis rendu compte de mon erreur. Mon workflow initial se basait sur des merge de develop dans master.

Mais plutôt que de recréer l’ensemble du dépôt et de rebaser tout ça, j’ai décidé de conserver cet historique en corrigeant le tir avec quelques commits. Il n’y a pas à rougir de faire des erreurs après tout, c’est ainsi qu’on apprend.

Déployer comme un prince

L’idée de base à présent, c’est de travailler sur vos fichiers sources dans develop. Puis, il faut que vous compiliez votre code, que vous changiez de branche, supprimiez ce qui n’a rien à faire là et ne conserviez que le code du site compilé final. La manière de procéder pour en arriver là est à votre entière disposition, tout dépend de votre façon de fonctionner.

Pour ma part, j’ai 2 solutions à vous proposer pour vous permettre de déployer tout ça plus facilement (= sans avoir à vous taper le process à la main) :

Vous vous faîtes un petit script de build qui vous permet de faire tout ça en une ligne de commande. C’est le cas de mon Makefile qui me permet de déployer en lançant un simple make deploy dans mon terminal. Libre à moi de pusher ensuite.
Vous pouvez aller jeter un oeil à git publish qui est un script que vous pouvez rajouter à Git et qui vous permettra de déployer des sites Jekyll avec ce workflow justement (quand on vous dit que d’autres y ont pensé avant vous).

Et voilà !

Nous y voilà, cela devrait fonctionner parfaitement à présent. Avec ces petits conseils vous devriez être en mesure de faire votre blog Jekyll, hébergé sur Github et multilingue \o/

Comme d’habitude, nhésitez pas à émettre commentaires, suggestions, remarques et autres questions qui vous trotteraient dans la tête, si besoin, ci-dessous.

Plop !

Bien isoler ses variables en Javascript

Sun, 19 May 2013 00:00:00 GMT

TL;DR

Ne pas se préoccuper de la portée des variables en Javascript, c’est aller au-devant de graves déconvenues. Il est important d’isoler l’environnement de son script afin de ne pas modifier involontairement des variables globales lors de son exécution.

Les fonctions anonymes auto-exécutantes (ou IIFE, selon) permettent donc d’isoler le code sans perturber son exécution :

;(function() {
  // votre code JS
})()

De plus, elle rendent le code plus flexible et robuste en permettant de créer des alias aux variables globales passées en paramètre :

;(function(window, $) {
  // votre code JS
})(window, jQuery)

Enveloppé, Piqué, Porté(e) !

Je laisse les premiers points aux Étoiles et je me concentrerais ici sur la question de la portée des variables en Javascript. Ce point, auquel on ne songe pas assez, est en effet susceptible de causer bien des soucis à grande échelle si l’on n’y prend pas garde.

Pour faire simple, il serait fort regrettable que le script que l’on est en train d’écrire ne se comporte pas comme prévu parce-que la variable gobgob que l’on déclare est déjà utilisée ailleurs et qu’on n’y a pas fait attention.

Il serait également gênant que notre superbe plugin de slideshow se mettent à planter complètement à l’exécution de notre script. Pourquoi ? Parce-que nous n’aurons pas pris garde au fait que ce magnifique plugin utilise la même variable que nous, et que nous venons tout juste de changer sa valeur (du coup) !

Pour éviter ce genre de scénario bien fâcheux, il faut isoler les variables de notre script du reste de l’environnement. C’est tout à fait réalisable et, si ce plugin avait été si magnifique que ça, c’est ce qu’il aurait fait !

Petit rappel sur la portée des variables en JS

En déclarant une variable comme il se doit, celle-ci est accessible à tout le script dans lequel elle est contenue, y compris dans les fonctions qui y sont déclarées.

var gobgob = 'Hey !'
function maFonction() {
  console.log(gobgob)
}

// Renvoie "Hey !"
maFonction()

En revanche, une variable proprement déclarée dans une fonction n’est pas accessible à l’extérieur de celle-ci : elle est isolée dans la fonction.

Cependant, le fait d’omettre le mot clef var lors de la déclaration d’une variable rend celle-ci globale, c’est à dire accessible depuis tout le script (ce qui, en général, n’est pas très très propre).

function maFonction() {
  var gobgob = 'Hey !'
  gubgub = 'Ho !'
}

maFonction()

// Renvoie "ReferenceError: gobgob is not defined"
console.log(gobgob)

// Renvoie "Ho !"
console.log(gubgub)

Ce que nous souhaitons, c’est faire en sorte que les variables de notre script ne viennent pas modifier d’éventuelles variables qui existeraient déjà ailleurs !

var gobgob = 'Hey!'

// (…)
// Quelque part, bien loin dans votre JavaScript…
// … une surchage sauvage d'une variable existante (et oubliée) apparaît !
var gobgob = 'Ho!'

Sortez couverts !

Pour résoudre nos soucis, il s’agit donc d’isoler les variables afin de limiter leur portée au seul endroit qui nous intéresse et ne pas venir redéfinir par mégarde des variables ou polluer l’environnement (écologie toussa toussa) avec des variables globales qui n’ont pas lieu d’être.

Pour cela, il s’agit d’envelopper notre code Javascript dans ce que l’on appelle basiquement une fonction anonyme auto-exécutante :

;(function() {
  // votre code JS
})()

Cette encapsulation est donc :

anonyme car la fonction ne porte pas de nom
auto-exécutante car elle est interprétée directement grâce au petit (); final

Pour reprendre notre exemple précédent :

var gobgob = 'Hey !'

// On enveloppe notre script comme il faut
;(function() {
  var gobgob = 'Ho!'

  // Renvoie "Ho!"
  console.log(gobgob)
})()

// Renvoie "Hey !" -> bingo !
console.log(gobgob)

Rien n’est boulversé dans l’exécution du script.

Par contre, nous n’avons plus à nous soucier des autres variables qui peuvent exister à partir du moment où nous travaillons dans notre environnement isolé : nous ne venons pas modifier par mégarde une variable globale !

En revanche, rien ne nous empêche d’utiliser une variable globale pour autant :

var gobgob = 'Hey !'
;(function() {
  // Renvoie "Hey !"
  console.log(gobgob)
})()

Renommer des variables globales dans notre script

Il est également possible de passer des variables en paramètre, généralement afin de les redéfinir pour l’usage de notre script. C’est d’ailleurs une bonne pratique à adopter lorsque vous travailler avec une librairie telle que jQuery !

Imaginez que vous souhaitiez créer un petit script sympatoche. Si vous utilisez jQuery, vous allez probablement utiliser des $ à gogo !

Seulement, que se passe-t-il si demain une autre bibliothèque vient complémenter jQuery et utilise également le $ comme référence ? Vous aller passer jQuery en mode noConflict()… et vous allez devoir reprendre votre script pour transformer tous vos $ en jQuery.

Ou alors, vous avez retenu ce que vous avez lu ici et 2 lignes de code vous permettront d’isoler bien proprement votre script, qui s’exécutera quoiqu’il arrive :

;(function($) {
  // votre script JS avec des $ tout partout
})(jQuery)

L’avantage de cette technique c’est que vous pouvez rapidement switcher de librairie sans modifier votre script, qui gagne donc en flexibilité et stabilité :

;(function($) {
  // votre script JS avec des $ tout partout
})(Zepto)

Note performance - Le double effet Kiss Cool de cette technique intervient lors de la minification de votre script. En effet, il sera possible de minifier les noms de toutes vos variables sans affecter le code (puisqu’il s’agit ni plus ni moins d’alias au final), donc de gagner de la place.

// Exemple où les occurrences à `window` ont été minimifiées
;(function(a) {
  console.log(a === window) // Renvoie `true`
})(window)

Astuce : Créer un alias pour `undefined`

Une bonne pratique, qui est également utilisée dans le code source de jQuery, consiste à déclarer un paramètre supplémentaire non défini, qui vaudra alors undefined dans votre script :

;(function(window, $, undefined) {
  // Crée une variable gobgob valant `undefined`
  var gobgob
  console.log(gobgob === undefined) // Renvoie `true`

  // Notre dernière variable est donc un alias pour `undefined`
})(window, jQuery)

Astuce bis : Accéder au variables, en dehors

Merci @fabien0102 pour m’avoir fait remarquer qu’il manquait ce point de détail.

Isoler son code, c’est bien. Mais parfois, on développe un plugin/une librairie et on aimerait bien pouvoir accéder à notre objet de l’extérieur, histoire de pouvoir s’en servir.

Il existe probablement différentes alternatives, mais en voici une toute simple : il suffit d’attacher notre variable à window, et ça marche.

;(function(window, undefined) {
  // Crée une variable gobgob et l'attache à window
  var gobgob = 'Hey !'
  window.gobgob = gobgob
})(window)

// Renvoie "Hey !"
console.log(gobgob)

Le mot de la fin

Cet article français se place dans la lignée des bonnes pratiques Javascript. C’est un premier pas vers l’élaboration de splendides scripts modulaires qui sont les composantes de plus gros projets.

Ce n’est pas quelque chose de radicalement nouveau pour autant, bien qu’il n’y ait pas masse d’articles francophones sur la question (à ce niveau là, il faut généralement se mettre à la langue de Shakespeare).

Enfin, je trouvais que cela faisait une bonne mise en pied à l’explication du fonctionnement d’un plugin jQuery (ça c’est du teasing).

Comme d’habitude, n’hésitez pas à émettre remarques, suggestions et questions aussi diverses que variées ci-dessous.

Plop !

Properly isolate your variables in JavaScript

Sun, 19 May 2013 00:00:00 GMT

TL;DR

If you don’t care about variable scoping in JavaScript, you may face some unpleasant troubles. Properly isolate your script environment is a best practice to have so you don’t override global variables when it executes.

Immediately-invoked function expressions (IIFE) allow you do to that:

;(function() {
  // your JS code
})()

Moreover, it makes your code flexible and robust so you can create global variables aliases as parameters for your script:

;(function(window, $) {
  // your JS code
})(window, jQuery)

It’s all about scope

I bet you wouldn’t like your new script not to behave as you want because the gobgob variable you use is already declared somewhere else and you didn’t pay attention for that.

I would even be worse if your splendid slideshow plugin starts going wrong when your new script is executing. Why? Because you didn’t notice that this plugin use the same variable you do and that you just change its value - if so, it wouldn’t be such a splendid plugin by the way.

To avoid that kind of scenario, you have to isolate your script from the rest of the environment, so it’s still safe. It’s dead easy to do and, if your slideshow plugin were a good one, that’s what it should have done!

Few reminder about scope in JS

If you declare properly a variable, it would be accessible from the whole script which is inside it’s container.

var gobgob = 'Hey!'
function myFonction() {
  console.log(gobgob)
}

// Outputs "Hey!"
myFonction()

On the contrary, a variable properly declared into a function is not accesible from the outside of this function: the scope is limited to the function.

However, if you forget to use the var keyword when you declare your variable, you’ll make it global which means it would be accessible from anywhere - which is generally not a best practice.

function myFonction() {
  var gobgob = 'Hey!'
  gubgub = 'Ho!'
}

myFonction()

// Outputs "ReferenceError: gobgob is not defined"
console.log(gobgob)

// Outputs "Ho!"
console.log(gubgub)

We don’t want our script variables override any other variables which would eventually exists!

var gobgob = 'Hey!'

// (…)
// Somewhere else far far away in your JavaScript…
// … a wild override of an existing (and forgetted) variable appears!
var gobgob = 'Ho!'

Don’t forget the love glove!

To resolve our problem, we just need to isolate variables so we limit their scope to the code we decided to.

To do so, we wrap our JavaScript code into what we called an IIFE - or a self-executing anonymous function apparently - :

;(function() {
  // your JS code
})()

This code encapsulation is:

anonymous because you don’t name the function
self-executing or immediately-invoked thanks to the final little ();

Going back to our previous example:

var gobgob = 'Hey!'

// We wrap our script properly
;(function() {
  var gobgob = 'Ho!'

  // Outputs "Ho!"
  console.log(gobgob)
})()

// Outputs "Hey!" -> bingo !
console.log(gobgob)

Nothing is changed for script execution.

But we don’t have to worry about other variables which could exist because we now work into a safe environment: we won’t modify a global variable inadvertently!

However, we can still use global variables inside our code:

var gobgob = 'Hey!'
;(function() {
  // Outputs "Hey!"
  console.log(gobgob)
})()

Rename global variables in our script

It’s even possible to pass variables as parameters for your script. You can generally redefine them for your script usage, which is good if you’re working with some library such as jQuery.

Imagine you’d like to create a tiny nice script using jQuery. You’d probably use $ everywhere.

What if I told you we’re now using another library which also uses $ as an alias? You’d probably pass jQuery in noConflict() mode… and you’ll have to change your script to replace $ with jQuery.

Or you’d have listen to me and these two lines of code would have properly isolate your script which would execute, regardless of your environment:

;(function($) {
  // your JS script with a bunch of $
})(jQuery)

The good part of this technique is that you could quickly switch library without changing anything in your script, which is more flexible and stable:

;(function($) {
  // your JS script with a bunch of $
})(Zepto)

Performance note - When you minify your script, it’d minify your variables’ name without ruining your code, so it would make it even smaller as a result.

// Example with minification for `window`
;(function(a) {
  console.log(a === window) // Outputs `true`
})(window)

Tip 1: Create an alias for `undefined`

One of JS best practice that jQuery uses in its source code is to declare a last parameter which is not defined and would be equal to undefined in your script:

;(function(window, $, undefined) {
  // Create a gobgob variable which value is `undefined`
  var gobgob
  console.log(gobgob === undefined) // Outputs `true`

  // Our last variable is an alias for `undefined`
})(window, jQuery)

Tip 2: Still access to variables, from the outside

Thanks @fabien0102 for pointing this was missing.

Isolate your code is good. But you’d sometimes need to develop a plugin/a library and you’d like to access the main object from the outside, so you can use it.

There are a bunch of possibilities but here is, IMHO, the simplest one: you just need to attach your variable to window so it becomes global for the other scripts.

;(function(window, undefined) {
  // Create a gobgob variable and attach it to window
  var gobgob = 'Hey!'
  window.gobgob = gobgob
})(window)

// Outputs "Hey!"
console.log(gobgob)

Final words

This post is not a really new one and you can find a bunch of that kind all over the web. But it’s still a few reminder to start thinking about modular scripts which are components for bigger projects.

Finally, the most we speak about that, the most developers are likely to use this best practice.

As usual don’t hesitate to leave me comments, suggestions or even questions if you need to.

Plop!

Tombez pour SMACSS

Thu, 16 May 2013 00:00:00 GMT

TL;DR

SMACSS est un ensemble de conseils et de lignes de conduite élaborés par Jonathan Snoovvk et dont le but est de vous permettre d’organiser votre CSS de manière claire et intelligente.

Le premier principe réside dans la catégorisation : on distingue et regroupe les règles CSS par affinité logique afin de structurer son code (base, layout, module, state, theme).

Le second principe relève de la convention de nommage : ne pas utiliser des ID quand une classe fait très bien l’affaire, nommer les classes de manière à faire ressortir la logique qui s’y cache, …

Le troisième principe consiste à découpler le HTML du CSS : garder chaque module indépendant du contexte HTML dans lequel il se trouve, utiliser les sélecteurs d’enfants à bon escient, …

Avec ces 3 principes, SMACSS vous permet de poser des bases solides pour un CSS de qualité, made in Canada !

Principe et intérêts

Il arrive bien (trop) souvent que l’organisation du CSS d’un projet web soit vraiment, vraiment mauvaise.

La raison à cela étant que les gens considèrent que le CSS c’est facile : des sélecteurs, des attributs, des valeurs et roule ma poule ! Si bien que la plupart des projets sur lesquels j’ai travaillé tendent à organiser leur CSS de manière “naturelle”, à savoir :

un éventuel reset CSS ou autre framework de base,
un fichier CSS principal pour tout ce qui est commun sur l’ensemble du site,
un fichier CSS spécifique par page lorsqu’il est nécessaire d’ajouter du style,
d’autres fichiers éventuels plus ou moins pertinents (“le CSS du carousel jQuery qu’on a choppé sur le web” en fait partie)

Les problèmes sont alors présents et de plus en plus évidents à mesure que le projet évolue :

on ne livre pas un seul et unique fichier CSS compressé par page, comme il le faudrait
on duplique les propriétés et le code qui va avec
on ne sait plus où sont rangées les règles correspondant au formulaire X
on galère pour maintenir le CSS, on préfère rajouter des règles les unes par dessus les autres
on se demande où placer cette règle qui apparaît sur quelques pages… mais pas toutes
on a oublié de racheter du café et c’est dimanche
etc.

Bref, c’est le bordel dans votre CSS !

La méthode Scalable and Modular Architecture for CSS (SMACSS) a pour but de venir organiser tout ça selon un ensemble de lignes de conduite assez simples à appréhender.

Ce n’est pas un framework au sens rigide du terme, mais des bonnes pratiques pour garder un code clairement architecturé et aisé à maintenir.

La philosophie SMACSS repose sur ces 3 grands principes que je vais détailler par la suite :

Les 3 grands principes de SMACSS

Catégoriser son CSS

La première considération de SMACSS consiste à regrouper les règles CSS selon des catégories qui vont définir l’organisation du code.

La catégorisation est le principe central de SMACSS. Le fait de catégoriser les règles permet de distinguer des modèles type et de définir des bonnes pratiques pour chacunes de ces catégories.

On distingue 5 types de catégories :

Base
Layout
Module
State
Theme

Base

Il s’agit des éléments par défaut tels qu’ils sont définis sur l’ensemble du site. Ce sont les règles de style “de base” (sans blague).

Bien généralement il s’agit des éléments HTML basiques.
Mais on peut également y retrouver des sélecteurs descendants (h1 em), des sélecteurs d’enfants (ul > li) ou même des pseudo-classes (a:hover).

Cette catégorie ne doit contenir ni classe, ni identifiant !
Vous ne devez pas utiliser !important dans cette catégorie.

/* Exemple des styles de base de ce blog */
body {
  background-color: #000;
  background-image: url('/assets/img/background.png');
  color: #fff;
  font-family: 'Roboto', sans-serif;
}

h1 {
  color: #f44;
}

h1,
h2,
h3 {
  font-family: 'Snippet', sans-serif;
}

h1 > span,
h2 > span,
h3 > span {
  color: #333;
  font-weight: normal;
}

em {
  font-style: normal;
  font-family: 'Snippet', sans-serif;
}

Les resets CSS font partie de cette catégorie.

Layout

Il s’agit du découpage de l’architecture de votre site en sections principales.

Généralement, il s’agit de sélecteurs simples, descendants ou d’enfants, voire de classes ou d’identifiants (pour le coup, c’est bien le seul endroit où l’usage d’ID est tolérable).

Vous ne devez pas utiliser !important dans cette catégorie.

Découpage du site en sections majeures pour le layout

/* Exemple des styles layout de ce blog */
.container {
  margin-right: auto;
  margin-left: auto;
  padding: 0 20px;
  max-width: 1050px;
}

header > img,
header > nav {
  line-height: 80px;
}

footer {
  font-size: 12px;
  font-size: 0.75rem;
  line-height: 2;

  padding-top: 10px;
  font-weight: 100;
}

Attention à ne pas confondre le layout et les modules !

Le layout correspond aux sections majeures de votre site, ce sont les grandes parties de votre template (le header, le footer, la sidebar, …).

Les modules correspondent aux sections mineures qui peuvent apparaître sur votre site (menu de navigation, formulaire de connexion, …). Le layout peut contenir un ou plusieurs modules.

Module

Un module est une section mineure, un composant autonome de la page.

Partir sur une structure modulaire est une bonne pratique à appliquer pour créer et maintenir un CSS flexible et réutilisable. A titre d’exemple, les modules les plus classiques sont certainement la navigation et les boutons.

Vous ne devez pas utiliser d’ID ou !important dans cette catégorie.

Mise en lumière des modules de la page

/* Exemple des styles du module block-list de ce blog */
.block-list {
  list-style: none;
  margin-left: 0;
}

.block-list > li {
  padding: 12px;
  border: 0 dashed #ddd;
  border-bottom-width: 1px;
}

.block-list > li:last-child {
  border: none;
}

.block-list__link {
  display: block;
  padding: 12px;
  margin: -12px;
}

Le plus complexe dans l’élaboration des modules est certainement le fait de devoir prendre garde à ce qu’ils soient modulaires, justement.

Un module doit être un bloc autonome et la structure des sélecteurs doit refléter cela. Si vous commencez à ajouter un contexte spécifique dans votre CSS pour styliser votre module “en fonction de là où il se trouve”, vous passez à côté de la plaque !

Il faut penser modularité et réusabilité.

header .block-list {
} /* Mauvaise idée =( */

.block-list-fit {
} /* Bien mieux ! */

<!-- Utilisation concrète -->
<header>
    <ul class="block-list block-list-fit">
        <li>Lorem ipsum dolor sit amet</li>
        <li>Possimus est fugit reiciendis</li>
        <li>Nostrum, ducimus, temporibus</li>
    </ul>
</header>

Ainsi, rien ne vous empêche d’appliquer le modificateur .block-list-fit ailleurs, ou de le retirer si besoin. C’est un Lego qui apporte sa pierre à l’édifice de votre design.

State

Il s’agit de classes qui viennent définir un état particulier dans lequel se trouvent vos éléments.

Généralement, une règle qui se trouve dans cette catégorie correspond à une simple classe CSS.

C’est la seule catégorie où l’usage de !important peut être toléré, voire recommandé.

En effet, ce genre de règles déterminent un état final du design, qui doit s’appliquer quoiqu’il advienne. Si votre code est propre, vous ne devriez pas avoir deux états s’appliquant sur le même élément et modifiant les mêmes attributs (sinon, vous avez un petit soucis de logique).

Exemple des différents états possibles d'un bouton

/* Exemple des styles state d'un projet */
.is-block {
  display: block  !important;
}

.is-dragged {
  color: rgb(0, 85, 128)  !important;
  background-color: rgb(217, 237, 247)  !important;
}

Bien souvent, les états correspondent à des interactions avec l’utilisateur et ont des dépendances avec Javascript.

En effet, quoi de plus simple que de rajouter et d’enlever une classe .is-loading sur la page pour faire un retour à l’utilisateur du traitement de sa requête ? Le JS n’en est que plus simple :

// Exemple d'utilisation lors d'un traitement de formulaire
$('form#update-quantity')
  .find('input')
  .change(function() {
    // Ajoute le loading sur la page (calcul en cours)
    $('#content').addClass('is-loading')

    // Requête AJAX pour mettre directement à jour le formulaire
    $.ajax({
      url: '/cart/update/' + ref + '/' + quantity,
      dataType: 'json',
      success: function(data) {
        // Retire le loading (fin du calcul)
        $('#content').removeClass('is-loading')

        // …
      },
    })
  })

Exemple du loading sur la page

Exemple de l’utilisation de .is-loading lors de la modification d’un champ

Theme

Dans certains cas, il se peut qu’un projet nécessite l’élaboration de différents thèmes pouvant s’interchanger en fonction des choix de l’utilisateur ou de l’équipe.

Dans ces cas, on peut découpler l’apparence de la structure des modules (notamment) afin de pouvoir switcher facilement entre ces différents designs.

Il s’agit donc généralement de redéfinir les styles de base, de layout, de module ou même de state en indiquant de manière claire quelles sont les règles qui définissent le thème et quelles sont celles qui n’en font pas partie.

Bien souvent, séparer clairement ces règles en les regroupant dans un fichier CSS relatif au thème suffit à montrer cette distinction.

/* Exemple des styles d'un theme d'un projet */
body {
  font-family: 'Roboto', sans-serif;
}

header {
  background-color: #33f;
  color: #a66105;
}

.block-list > li {
  border: 0 dashed #00d;
}

/* Ou bien si le thème est interchangeable, on peut envisager ceci */
.theme-ocean {
  font-family: 'Roboto', sans-serif;
}

.theme-ocean header {
  background-color: #33f;
  color: #a66105;
}

.theme-ocean .block-list > li {
  border: 0 dashed #00d;
}

Bonus : Shame

Ce point ne fait pas véritablement partie de SMACSS, mais relève d’une idée/blague de Harry Roberts au détour d’un post. Tant qu’à y aller dans l’organisation du code, je trouvais pertinent de rajouter ce dernier point.

L’idée c’est que, dans la vraie vie, il arrive que les développeurs n’aient pas le temps de coder bien proprement une fonctionnalité de dernière minute ou bien qu’il soit nécessaire de rapidement corriger un problème sans qu’on n’ait vraiment eu le temps de comprendre ce qui n’allait pas.

Ainsi, en CSS comme ailleurs, il arrive de devoir faire un petit correctif rapide à grand coup de overflow:hidden; et autres !important.

Le problème, c’est que bien souvent les développeurs ne prennent pas (n’ont pas) le temps de venir faire le refactoring qui s’impose, histoire de nettoyer tout ça. Et ainsi le CSS se remplit de petits hacks divers et variés, dont on oublie la raison voire l’existence, et qui viennent saloper tout le travail (je vous raconte pas quand y’a plus d’un développeur sur le projet).

La solution est donc d’isoler ces petites magouilles dans un seul et même fichier : shame.css.

Le workflow est le suivant :

Si la règle CSS que l'on va rajouter est un hack, on la place dans shame.css
On commente le hack le mieux possible
- à quel code cela se réfère-t-il ?
- pourquoi c'était nécessaire ?
- comment ça fonctionne ?
- comment on pourrait le faire proprement en ayant plus de temps ?
On ne blâme pas le développeur s'il a correctement expliqué son hack
Quand on a du temps disponible, on vient nettoyer shame.css

Voici un exemple de hack (librement inspiré de celui de Harry) :

/**
 * Nav specificity fix.
 *
 * Quelqu'un a utilisé un ID dans le header (`#header a{}`)
 * qui l'emporte sur le sélecteur de nav (`.site-nav a{}`).
 * Utilisation de !important pour le surcharger d'ici qu'on ait
 * le temps de refactor le header.
 */
.site-nav a {
  color: #bada55  !important;
}

Si vous faîtes les choses correctement, vous devrez inclure ce fichier à la fin de votre CSS compressé final.

Nommer ses classes

En plus de la catégorisation des règles CSS et de la nouvelle structure que cela donne à notre code, il peut être particulièrement utile de convenir de certaines conventions de nommage au sein du projet.

Sans aller chercher très loin, c’est apporter une certaine rigueur et intelligence au code qui évitera aux futurs développeurs de venir se casser les dents sur des classes aux noms aléatoires.

Par exemple, .titre-bleu fait partie de ces fausses bonnes idées de début de projet. Si effectivement il s’agit de mettre le titre en bleu avec cette classe, qu’en sera-t-il dans 1 an lorsque finalement il aura été décrété que le rouge était plus tendance ? Changer le CSS ne fera que relever l’absurdité des ces .titre-bleu qui sont finalement rouges… Il faudra donc se taper toutes les occurences de cette classe dans le projet pour aller corriger le tir !

D’un autre côté, si le choix avait été porté sur .titre-festif (ou quelque chose d’aussi sémantique), alors il n’y aurait jamais eu de problème. C’est un concept de base qu’il faut bien assimiler si on veut éviter les erreurs qui coûtent (du temps, donc de l’argent).

D’une manière générale, la convention de nommage doit clarifier les intentions.

Voici quelques pistes :

pour les modules, il est judicieux que les classes partagent la même racine correspondant au module en question. Des projets comme Bootstrap adoptent d’ailleurs cette convention.

.btn {
}
.btn-search {
}
.btn-small {
}
.btn-large {
}
/* … */

pour state, il s’agit d’un état logique dans lequel se trouve un élément. Ainsi, il n’est pas bête que chaque classe transmettent cette intention avec .is- par exemple :

.is-loading {
}
.is-collapsed {
}

/* et pour les états relatifs à un module… */
.is-btn-active {
}
.is-btn-disabled {
}

pour les themes donc, il est envisageable de créer une sorte de namespace explicite, notamment s’il est possible de switcher entre les différents thèmes proposés :

.theme-ocean {
}
.theme-silver {
}
/* … */

Découpler le HTML du CSS

Ce point recoupe de manière assez explicite les bonnes pratiques d’OOCSS que j’avais introduites il y a quelque temps.

Le principe est donc le même : le CSS doit être indépendant du contexte HTML dans lequel les éléments se trouvent.

C’est la condition sine qua none d’un code flexible, modulaire et réutilisable. C’est d’autant plus vrai quand vous pensez aux modules qui constituent une bonne partie de votre CSS une fois les bases et le layout posés.

De plus, faîtes en sorte que vos modules aient une structure prédictible ! Pour cela, utilisez les sélecteurs d’enfants et ne soyez pas trop génériques, au risque de ne pas envisager tous les cas de figure.

Enfin, si le HTML n’est pas prédictible, créez une classe !

Des modules prédictibles

Pour reprendre l’exemple employé par Jonathan Snoovvk, voici un code à problème :

<!-- Un menu de navigation classique -->

<ul class="nav">
    <li><a href="/">Accueil</a></li>
    <li><a href="/products">Nos produits</a></li>
    <li><a href="/contact">Contactez-nois</a></li>
</ul>

.nav {
  margin: 0;
  padding: 0;
  list-style: none;
}

.nav li {
  float: left;
}

.nav li a {
  display: block;
  padding: 5px 10px;
  background-color: blue;
}

C’est un cas de figure tout ce qu’il y a de plus classique sur un projet et, jusqu’à présent, ça fonctionnait pas trop mal.

Seulement voilà, le projet évolue et le menu se développe, donnant quelque chose d’un peu plus complexe :

<!-- Un menu de navigation un peu plus cossu -->

<ul class="nav">
    <li><a href="/">Accueil</a></li>
    <li>
        <a href="/products">Nos produits</a>
        <ul>
            <li><a href="/products/shoes">Chaussures</a></li>
            <li><a href="/products/jackets">Blousons</a></li>
        </ul>
    </li>
    <li><a href="/contact">Contactez-nois</a></li>
</ul>

Et là, c’est le drame…

Le code précédent n’avait pas envisagé cette possibilité et voilà que le menu imbriqué hérite d’un design non désiré : le sous-menu est affecté par le float: left; qu’il faut à présent annuler (et pis le client, il voulait le sous-menu en rouge, paraît que c’est tendance).

Une fausse bonne idée (mais naturelle) pour corriger cela consiste à créer de nouvelles règles plus spécifiques :

.nav {
  margin: 0;
  padding: 0;
  list-style: none;
}

.nav li {
  float: left;
}

.nav li a {
  display: block;
  padding: 5px 10px;
  background-color: blue;
}

.nav li li {
  float: none;
}

.nav li li a {
  padding: 2px;
  background-color: red;
}

Et c’est ainsi que votre CSS devient petit à petit un joyeux bordel…

Avec SMACSS, vous auriez retenu le 3e principe et pris garde à ce que la structure de votre module soit prédictible :

<!-- Un menu de navigation un peu plus cossu -->

<ul class="nav">
    <li><a href="/">Accueil</a></li>
    <li>
        <a href="/products">Nos produits</a>
        <ul class="nav nav-imbricated">
            <li><a href="/products/shoes">Chaussures</a></li>
            <li><a href="/products/jackets">Blousons</a></li>
        </ul>
    </li>
    <li><a href="/contact">Contactez-nois</a></li>
</ul>

.nav {
  margin: 0;
  padding: 0;
  list-style: none;
}

.nav > li {
  float: left;
}

.nav > li > a {
  display: block;
  padding: 5px 10px;
  background-color: blue;
}

.nav-imbricated > li > a {
  padding: 2px;
  background-color: red;
}

Plus de problème de design du sous-menu : il suffit de lui appliquer une variante du menu de navigation. Plus besoin de devoir annuler le float: left; non désiré non plus, c’est goody !

Dans le doute, créez une classe

Parfois, il s’avère que la structure d’un module soit flexible et qu’il puisse contenir tout un tas d’éléments différents. Il serait alors absurde de vouloir envisager toutes les possibilités ainsi :

.media {
  overflow: hidden;
}

.media > div {
  float: left;
  margin-right: 20px;
}

.media > div img,
.media > p img {
  display: block;
}

.media > p,
.media > ul,
.media > div {
  overflow: hidden;
}

La solution à ce genre de problème consiste à créer une classe afin de définir la structure, quelque soit l’élément qui sera utilisé pour la sémantique HTML :

.media {
  overflow: hidden;
}

.media-img {
  float: left;
  margin-right: 20px;
}

.media-img img {
  display: block;
}

.media-body {
  overflow: hidden;
}

Ce qui peut être à nouveau simplifié et présente les bases du media object :

.media,
.media-body {
  overflow: hidden;
}
.media-img {
  float: left;
  margin-right: 20px;
}
.media-img img {
  display: block;
}

C’est ce que l’on appelle découpler le HTML du CSS \o/

Démonstration par l’exemple

Pour terminer sur la question, je me propose de vous présenter comment je met en application SMACSS dans l’organisation de mon CSS.

Prenons l’exemple de ce blog (dont le code est disponible sur Github). L’architecture du CSS se présente de la manière suivante (dossier /assets/less) :

.
|-- inuit.css/ # Framework inuit.css
|
|-- ui/
| |-- base.less # Éléments de base
| |-- layout.less # Structure globale
| |-- mod-block-list.less # Module block-list
| |-- mod-image.less # Module image
| |-- mod-island.less # Module island
| |-- mod-pagination.less # Module pagination
| (…)
| |-- (state.less) # Design des états possibles
|
|-- vars.less # Variables globales LESS
|-- nicoespeon.less # Fichier de setup

En pratique, c’est le fichier nicoespeon.less qui est interprété et qui s’occupe d’importer les fichiers utilisés dans le bon ordre, puis de compiler tout ça et de générer un seul et unique fichier CSS compressé, rangé dans /assets/css/nicoespeon.css.

Personnellement, j’ai choisi de préfixer les noms de chaque module par mod-. J’aurais également pu les placer dans un dossier modules/, tout comme inuit.css dispose du dossier objects/ qui remplit ni plus ni moins le même rôle.

C’est donc un choix personnel, et là est toute la question : à vous de prendre la philosophie et de l’adapter à votre réalité, à vos besoins… et de vous y tenir !

Conclusion

Voilà pour cette présentation de la philosophie SMACSS !

Bien évidemment, je vous suggère d’aller faire un tour du côté du site officiel :

Vous y trouverez l’essentiel du livre gratuitement. Vous pourrez également vous procurer le bouquin pour $15-20 si le cœur vous en dit (et disposer de conseils plus avancées sur la question).

Les images utilisées dans cet article sont tirées de ”Your CSS is a mess”, slideshow de Jonathan Snoovvk que je vous recommande.

Vous pouvez également jeter un oeil à son intervention à la Smashing Conference 2012.

Enfin, si vous avez des réactions à propos de cet article je vous en prie : faîtes donc ci-dessous !

Plop !

Déléguer les événements en jQuery

Mon, 13 May 2013 00:00:00 GMT

TL;DR

Jusqu’à jQuery 1.7 on faisait la distinction entre $.fn.bind, $.fn.live et $.fn.delegate afin de créer des écouteurs d’événements.

$.fn.bind est la manière la plus basique d’attacher un écouteur à un objet, généralement un noeud du DOM.

$.fn.live est plus puissant car il attache l’écouteur à la racine du document et fait vivre le comportement sur chaque élément du DOM correspondant, y compris ceux créés par la suite.

$.fn.delegate se comporte plus ou moins comme $.fn.live à ceci près que l’on spécifie un noeud du DOM où l’on attache notre écouteur live, ce qui est bien plus rapide à l’exécution.

$.fn.delegate est plus performant que $.fn.live qui est plus performant que $.fn.bind.

Depuis jQuery 1.7, toutes ces méthodes ont étés remplacées par l’unique méthode $.fn.on. Les principes de performance sont les mêmes, seule la syntaxe change.

Never gonna `bind` you up

C’est la méthode la plus élémentaire pour attacher un écouteur d’événements à un objet jQuery. Elle est généralement utilisée sur des éléments du DOM dans le but de créer des intéractions avec l’utilisateur :

// Utilisation basique de $.fn.bind
$('div#main-content').bind('click', function() {
  /* … */
})

Notre objet écoute désormais l’événement nommé 'click' et réagira à chaque fois que cet événement sera déclenché. Sur l’exemple précédent par exemple, la fonction définie sera déclenchée à chaque fois que l’on cliquera sur l’élément #main-content.

'click' est l’un des noms d’événements usuels qui dispose d’une méthode raccourcie équivalente :

// Équivalent du code précédent
$('div#main-content').click(function() {
  /* … */
})

Cependant, il est possible de spécifier n’importe quel nom d’événement utilisé dans le code. En fait, c’est le point de départ de la programmation événementielle en JS, permettant de créer des applications web avancées.

$('#foo').bind('my-event', function() {
  /* … */
})
$('#foo').trigger('my-event') // Déclenchera l'événement lié

La méthode pour arrêter un tel écouteur est $.fn.unbind.

Avant jQuery 1.7, c’était la manière la plus basique de faire les choses.

Born to be a `live`

Bien que le principe de $.fn.bind soit sympatoche, la méthode est assez limitée. Typiquement, elle a deux inconvénients :

Il attache un écouteur pour chacun des éléments qui correspondent au sélecteur, ce qui n’est pas la solution la plus optimale lorsque l’on cible plus d’un élément
Il attache un écouteur seuelement sur les éléments qui correspondent au sélecteur à ce moment précis, si vous modifiez le DOM et souhaitez créer de nouveaux éléments identiques, il vous faudra attacher les événements à nouveau.

// Pas glop…
$('a.tooltip').bind('click', function() {
  /* … */
})
// ou $('a.tooltip').click(function() { /* … */ });

La solution développée avant jQuery 1.7 était la méthode $.fn.live :

// Utilisation basique de $.fn.live
$('li.text-info').live('hover', function() {
  /* … */
})

Au lieu d’attacher un écouteur d’événements à chaque élément, il en attache un au niveau du document root. Ainsi, chaque nouvel élément qui correspond au sélecteur se comportera de la même manière. De plus, c’est bien plus efficace en termes de performance.

La méthode pour arrêter un tel écouteur est $.fn.die.

Cette méthode est dépréciée depuis jQuery 1.7, mais le principe reste le même, ce qui est bon à savoir.

Learn to `delegate`

La méthode $.fn.delegate est basiquement la même que $.fn.live, présentant les mêmes avantages par rapport à $.fn.bind:

// Utilisation basique de $.fn.delegate
$('ul#main-navigation').delegate('li.text-info', 'hover', function() {
  /* … */
})

Le truc c’est que, au lieu d’attacher chaque écouteur au document root, vous spécifiez l’élément du DOM où vous souhaitez porter votre attention. Ainsi, vous augmentez significativement la performance car c’est bien plus spécifique !

La méthode pour arrêter un tel écouteur est $.fn.undelegate.

Turn me `on`

Depuis jQuery 1.7, toutes les précédentes méthodes ont étés fusionnées dans une seule, puissante et unique méthode : $.fn.on.

Maintenant que vous avez compris comment les précédentes fonctionnent, voyons quels sont leur équivalent avec la syntaxe de celle-ci :

// Utilisation basique de $.fn.on au lieu de $.fn.bind
$('div#main-content').on('click', function() {
  /* … */
})

// Utilisation basique de $.fn.on au lieu de $.fn.live
$(document).on('hover', 'li.text-info', function() {
  /* … */
})

// Utilisation basique de $.fn.on au lieu de $.fn.delegate
$('ul#main-nav').on('hover', 'li.text-info', function() {
  /* … */
})

La distinction entre $.fn.live et $.fn.delegate et plus claire avec cette simple méthode, l’accent mis sur la délégation prend son sens (sauf si vous souhaitez explicitement attacher votre écouteur à la racine du document, ce qui est rare).

Vous pouvez également passer des event data via la méthode :

// Attache des données à l'événement
$('a').each(function(i) {
  $(this).on('click', { index: i }, function(e) {
    alert('My index is ' + e.data.index)
  })
})

L’utilisation de $.fn.on est instinctive et rend la gestion événementielle très facile à prendre en main avec jQuery!

La méthode pour arrêter un tel écouteur est… $.fn.off.

Et pour la performance ?

Comme expliqué, voici le listing des méthodes, de la plus performante à la moins performante :

.on(events, selector, [data,] handler) équivaut à $.fn.delegate
$(document).on(events, selector, [data,] handler) équivaut à $.fn.live
.on(events, [data,] handler) équivaut à $.fn.bind

Pour résumer :

Si vous avez besoin d’attacher un écouteur d’événements à plus d’un élément, utilisez .on(events, selector, [data,] handler)
Si vous n’avez pas d’ancre sur laquelle vous rattacher, utilisez $(document).on(events, selector, [data,] handler)
Sinon, utilisez .on(events, [data,] handler), ou la fonction raccourcie s’il y en a une

Conclusion

C’était un bref et gentil rappel sur la délégation des événements en jQuery.

Rien de nouveau sous le soleil mais cette article traite d’un point important. C’est un point à savoir que vous pouvez facilement retrouver sur le net en faisant quelques recherches.

Je me suis rendu compte il y a quelque temps que j’avais la fâcheuse tendance de toujours utiliser la fonction raccourcie, même pour traiter un certain nombre d’éléments, alors que j’aurais pu employer des méthodes bien plus efficaces. Lorsque vous vous retrouvez à gérer plus d’un élément, pensez à la méthode $.fn.on !

J’espère que ce petit point vous aura appris quelque chose ou rafraîchi la mémoire. Si c’est le cas, n’hésitez pas à me laisser votre opinion ci-dessous ;-)

Plop!

Event delegation in jQuery

Mon, 13 May 2013 00:00:00 GMT

TL;DR

Before jQuery 1.7 we used to distinguish $.fn.bind from $.fn.live and $.fn.delegate to create events listeners.

$.fn.bind is the most basic one which attach an event listener to an object, usually a DOM node.

$.fn.live is more powerful as it attach the event listener at the document root and makes the behavior live in every corresponding element of the DOM, even if they are created later.

$.fn.delegate behaves almost the same as $.fn.live, but you specify a DOM node where to attach your live listener, which is much more faster.

$.fn.delegate is more efficient than $.fn.live which is more efficient than $.fn.bind.

Since jQuery 1.7, all of these methods have been replaced by the $.fn.on method. Performance principles still the same, but the syntax changes.

Never gonna `bind` you up

The most basic method to attach an event listener to a jQuery object. It’s commonly used on DOM elements to create some interaction with the user:

// Basic use of $.fn.bind
$('div#main-content').bind('click', function() { … });

Your object is now listening at the event named 'click' and will do something everytime this event is triggered. With the previous code, for instance, the functon defined will be triggered everytime you click on the #main-content element.

'click' is one of the usual events name which has a shorthand method which is equivalent:

// Equivalent of the previous code
$('div#main-content').click(function() { … });

However, you can pass any event name you may have specify within your code. In fact, this is the key start for event-driven programming in JS, which helps to create advanced web-applications.

$('#foo').bind('my-event', function() { … });
$('#foo').trigger('my-event'); // Will trigger the binded event

The method to stop such an event listener is $.fn.unbind.

Until jQuery 1.7, this was the most basic way to do things.

Born to be a `live`

Although $.fn.bind principle is very nice, the method is very limited. It basically has two downsides:

It attaches an event listener for every single element which matches the selector, which is not the most efficient solution when you target more than one element
It attaches an event listener only for elements which matches the selector at this time, if you modify the DOM and want to create the same elements, you’ll need to bind events again.

// This sucks…
$('a.tooltip').bind('click', function() { … });
// or $('a.tooltip').click(function() { … });

The solution found before jQuery 1.7 was the $.fn.live method:

// Basic use of $.fn.live
$('li.text-info').live('hover', function() { … });

Instead of attaching an event listener to every single element, it attaches just one at the document root level. Doing so, any new element which matches the selector will behave the same. Futhermore, it’s much more efficient if you speak about performance.

The method to stop such an event listener is $.fn.die.

The method is deprecated since jQuery 1.7, but the principle still the same, which is good to keep in mind.

Learn to `delegate`

The $.fn.delegate method is basically the same than the $.fn.live, coming with the same advantages over $.fn.bind:

// Basic use of $.fn.delegate
$('ul#main-navigation').delegate('li.text-info', 'hover', function() { … });

The point is that, instead of attaching every event listener to the document root, you specify a DOM element where you want to focus. Doing so increase significantly performance as it’s much more specific!

The method to stop such an event listener is $.fn.undelegate.

Turn me `on`

Since jQuery 1.7, all of the previous methods have been merged into one single, powerful method: $.fn.on.

Now you’ve understood the previous ones, let see what are the equivalent syntaxes with the single new method:

// Basic use of $.fn.on instead of $.fn.bind
$('div#main-content').on('click', function() { … });

// Basic use of $.fn.on instead of $.fn.live
$(document).on('hover', 'li.text-info', function() { … });

// Basic use of $.fn.on instead of $.fn.delegate
$('ul#main-nav').on('hover', 'li.text-info', function() { … });

The distinction between $.fn.live and $.fn.delegate is more clear with that single method, and the emphasis on a powerful delegation makes sense (excepted if you explicitly want to attach your listener to the root of the document, which is rare).

You can either pass event data through the method:

// Give some data to the event
$('a').each(function(i) {
  $(this).on('click', { index: i }, function(e) {
    alert('My index is ' + e.data.index)
  })
})

The use of $.fn.on is pretty straightforward which makes event handling dead easy with jQuery!

The method to stop such an event listener is… $.fn.off.

What about performance?

As explained, here are the list of methods from the most efficient to the less one:

.on(events, selector, [data,] handler) equivalent to $.fn.delegate
$(document).on(events, selector, [data,] handler) equivalent to $.fn.live
.on(events, [data,] handler) equivalent to $.fn.bind

In a nutshell:

If you need to attach an event listener to more than one element, use .on(events, selector, [data,] handler)
If don’t have any anchor to focus on, use $(document).on(events, selector, [data,] handler)
Otherwise, use .on(events, [data,] handler), or the shorthand function if exists

Conclusion

This was a short and friendly reminder about event delegation in jQuery.

No hot news but such a big deal in this article. That was a point worth noting you could also find easily, doing some researches through the Internet.

I realized very few time ago that I always used shorthand functions, dealing with a bunch of DOM elements sometimes, when I could have used more efficient methods. When you’ve to deal with more than one element, think about the $.fn.on method!

I hope this have you learn something or refresh your mind on that point. If so, don’t hesitate to leave me comment below ;-)

Plop!

Plongée au coeur de l'OOCSS

Wed, 08 May 2013 00:00:00 GMT

TL;DR

“C’est comme j’te dis tu fais du CSS et tu te base sur le contexte ! Non mais all’OOCSS ! J’sais pas vous m’recevez ?”

− Margina Remattia, OOCSS Evangelist

OOCSS, c’est quoi ?

Considérons un projet web qui débute : une start-up lambda qui se rêve de développer LA web-application incontournable du web de demain. La start-up veut bien faire et choisi judicieusement les technos, frameworks et environnements… Mais quoiqu’il en soit, le rendu front-end sera le même : HTML, CSS et Javascript.

Seulement voilà, si l’ensemble de l’application bénéficiera sûrement des avantages de quelques frameworks, jeter un coup d’oeil du côté de la feuille de style donnera probablement quelque chose dans ce goût là (avec ou sans pré-processeur) :

#generateur-formulaire {
  width: 760px;
  margin: auto;
}

#generateur-formulaire label {
  font-weight: bold;
  font-size: 12px;
  /* … */
}

#generateur-formulaire label.champ-titre {
  font-weight: normal;
  font-size: 11px;
  /* … */
}

#generateur-formulaire textarea {
  width: 350px;
}

#generateur-formulaire .big textarea {
  width: 500px;
}

/* tout plein de CSS */

Or ce code va poser un certain nombre de problèmes avec le temps :

Manque de flexibilité, il ne peut s’appliquer qu’aux éléments contenus dans le formulaire portant l’identifiant #generateur-formulaire. Ca peut paraître pertinent au début, mais quid si demain une autre page du site présente deux formulaires à l’apparence similaire ?
Trop de spécificité, il oblige à accentuer toujours plus la spécificité des sélecteurs si l’on souhaite rajouter un cas particulier (label.champ-titre ou .big textarea par exemple).
Trop compliqué, sa maintenance nécessite d’être un expert et de connaître l’architecture de chaque page pour décortiquer tout ce bazar. D’autant que cela promet de grossir encore et encore à mesure que le site se développe.

Ajoutez à cela une organisation plus ou moins claire des fichiers CSS et vous obtenez un joli code spaghetti propice aux erreurs et à la duplication de code, surtout si d’autres développeurs se rajoutent au projet par la suite.

Cette extrême dépendance à la structure HTML rend le code particulièrement fragile : même avec le code le plus propre qu’il soit, une simple maladresse d’un non-expert peut le ruiner complètement.

Bref, autant de signes de non-maturité qui risquent, à la longue, de lui compliquer la tâche à notre start-up, lui promettant de longues nuits blanches de debuggage et de refactoring.

Finalement, le soucis de ce code réside dans la relation 1:1 que le CSS entretient avec le nombre de blocs, de pages et de modules du site. A mesure que le site grossit, le CSS grossit tout autant. Ca demande du temps de développement, donc de l’argent… On a vu mieux en terme de ROI !

Librement inspiré par Jonathan Snoovvk =)

L’Object Oriented CSS (OOCSS) vient apporter sa solution à tous ces problèmes. Il ne s’agit pas d’un pré-processeur, ni même d’un nouveau langage, mais plutôt d’une philosphie de code. C’est un ensemble de bonnes pratiques, de règles et de conseils.

L’OOCSS repose sur 2 grands principes :

Séparation de la structure et de l’apparence
Séparation du conteneur et du contenu

1. Séparation de la structure et de l’apparence

Les éléments d’un site web ont généralement un aspect visuel qui se répètent dans différents contextes (couleurs, police, bordures, bref… charte graphique). C’est l’apparence.

Dans le même temps, un certain nombre de propriétés “invisibles” sont également répétés (dimensions des blocs, overflow, etc.). C’est la structure.

Le fait de distinguer les deux permet de créer des éléments ré-utilisables à souhait sur d’autres éléments partageant les mêmes propriétés : on parle alors d’objets (ce qui devrait sonner familier aux développeurs back-end, soit dit en passant).

2. Séparation du conteneur et du contenu

On parle ici de ne pas limiter bêtement le style d’un élément (le contenu) au contexte dans lequel il se trouve (le conteneur).

Si l’on stylise les titres, pourquoi se limiter à ceux du <header>, simplement parce-que c’est le seul titre actuel ? Il y a même de fortes chances, si notre design est un tant soit peu homogène, que les titres se comportent sensiblement de la même façon sur l’ensemble des pages du site, question d’ergonomie.

C’est encore plus vrai pour les modules.

OOCSS, pourquoi c’est bien ?

Les 10 bonnes pratiques

Voici la liste des 10 bonnes pratiques qui forment l’esprit de l’OOCSS :

Créer une bibliothèque par composant
Chaque composant (bouton, tableau, lien, image, clearfix, etc.) doit être tel un Lego = combinable et réutilisable à souhait.
Utiliser des styles sémantiques et consistants
Le style d’un nouvel élément créé en HTML doit être prévisible.
Designer des modules transparents
Le module est le cadre conteneur pouvant être utilisé avec n’importe quel contenu.
Être flexible
Les hauteurs et largeurs doivent être extensibles et s’adapter (RWD inside).
Apprendre à aimer les grilles
Les grilles permettent de contrôler la largeur, la hauteur se gère par le contenu.
Minimiser les sélecteurs
S’en tenir à une spécificité [0-0-1-0] permet un meilleur contrôle sur les sélecteurs.
Séparer la structure de l’apparence
Il faut distinguer les deux, c’est un principe fondamental de l’OOCSS. Elaborez des objets abstraits pour la structure des blocs et des classes pour habiller ces blocs, indépendamment de leur nature.
Séparer le conteneur du contenu
Il faut distinguer les deux, c’est un principe fondamental de l’OOCSS. Construisez des relations 1:n en décomposant conteneur et contenu.
Étendre les objets en appliquant de multiples classes aux éléments Les classes/objets sont autant de Legos qui s’assemblent pour obtenir le résultat désiré.
Utiliser les resets et les fonts YUI
C’est un choix relatif du framework OOCSS.

Les Legos d’abord - Une bonne pratique consiste également à styliser les pages individuelles après que tous les composants basiques aient étés créés.

Les 9 pièges à éviter

Voici la liste des 9 erreurs à bannir selon l’esprit OOCSS :

Créer des styles dépendant du contexte
Il n’y a rien de moins flexible qu’un sélecteur du genre article > p:nth-child(2) > span.plop ou autres fantaisies.
Spécifier le tag auquel s’applique une classe
div.ma-classe est inutilement spécifique, .ma-classe suffit tout autant. En revanche, c’est tout à fait pertinent s’il s’agit de surcharger une classe pour certains éléments spécifiques (strong.error permet de surcharger les règles par défaut de .error).
Utiliser des identifiants
Ce qu’un identifiant peut faire, une classe le fait tout autant ; la réciproque est en revanche fausse. De plus, les identifiants contribuent à créer des problèmes de spécificité.
Utiliser des ombres et des bords arrondis sur des backgrounds irréguliers
Ca tend à donner des résultats inattendus.
Faire une sprite contenant toutes les images (sauf s’il y a très peu de pages)
C’est pas très très optimal non plus sachant qu’il faut alors tout gérer en CSS.
Ajuster très précisément la hauteur
La hauteur d’un élément se contrôle par le contenu. Différencier le conteneur du contenu vous simplifiera la vie.
Utiliser des images comme des textes
Niveau accessibilité on fait mieux.
Faire de la redondance
Deux composants qui se ressemblent trop pour être différenciés sur une même page, se ressemblent trop pour être utilisés sur le site : choisissez-en un !
Faire de l’optimisation précoce
Les développeurs ont tendance à perdre plus de temps à réfléchir à l’optimisation de parties non critiques avant de se concentrer sur l’essentiel.

Les avantages de l’OOCSS

Au fur et à mesure que le projet avance, il devient possible de créer de nouvelles pages en combinant les composants de sorte qu’il n’est plus nécessaire de rajouter du CSS, même pour une architecture complètement différente.

Réutiliser les éléments est également un gain de performance totalement gratuit ! Vous créez de nouveaux éléments avec 0 ligne de code CSS, on peut difficilement faire mieux.

L’OOCSS nous force à penser le site dans sa globalité plutôt que de simples pages mises les unes à côtés des autres. Il s’agit d’anticiper l’avenir.

Enfin, le principal avantage de cette philosophie selon moi est qu’elle rend le CSS modulaire, donc plus facilement maintenable dans le temps. Cette modularité rend le CSS plus robuste : un nouveau développeur sur le projet aura moins de chance de tout casser en travaillant dessus.

OOCSS, comment ça marche ?

Des exemples concrets

Souvenez-vous des 2 grands principes de la philosophie :

Séparation de la structure et de l’apparence
Séparation du conteneur et du contenu

Avec les bonnes pratiques en tête, voyons comment l’appliquer sur un code de tout les jours.

1. Séparation de la structure et de l’apparence

Pour reprendre l’éternel exemple du bouton, un code CSS “classique” ressemble souvent à cela :

#button {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

#button-primary {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #ffffff;
  text-align: center;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  vertical-align: middle;
  cursor: pointer;

  background-color: #006dcc;
}

#button-large {
  display: inline-block;
  padding: 8px 16px;
  margin-bottom: 0;

  font-size: 18px;
  line-height: 28px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

#button-activation {
  display: inline-block;
  padding: 8px 16px;
  margin-bottom: 0;

  font-size: 18px;
  line-height: 28px;
  color: #ffffff;
  text-align: center;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  vertical-align: middle;
  cursor: pointer;

  background-color: #006dcc;
}

<!-- Le HTML correspondant -->
<a href="#" id="button">Default</a>
<a href="#" id="button-primary">Primary</a>
<a href="#" id="button-large">Large</a>
<a href="#" id="button-activation">Large Primary</a>

Au final, beaucoup de redondance et un #bouton-activation qui n’est que la version large du #bouton-primary.

En retravaillant le CSS avec OOCSS, on obtient quelque chose de beaucoup plus flexible :

.button {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

.button-primary {
  color: #ffffff;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  background-color: #006dcc;
}

.button-large {
  padding: 8px 16px;

  font-size: 18px;
  line-height: 28px;
}

<!-- Le HTML correspondant -->
<a href="#" class="button">Default</a>
<a href="#" class="button button-primary">Primary</a>
<a href="#" class="button button-large">Large</a>
<a href="#" class="button button-large button-primary">Large Primary</a>

.button définit les propriétés génériques (et ici “par défaut”) de nos boutons. En le surchargeant, l’on obtient des classes qui peuvent se combiner pour donner le résultat attendu, tels des Lego !

Et elle est là l’astuce.

2. Séparation du conteneur et du contenu

Il n’est pas rare au cours du développement du design principal de se retrouver avec un code ressemblant à cela :

header h1 {
  font-family: 'Roboto', Helvetica, sans-serif;
  font-size: 2em;

  color: #f44;
}

/* tout plein de code CSS */

footer h1 {
  font-family: 'Roboto', Helvetica, sans-serif;
  font-size: 1.5em;

  color: #f44;
  opacity: 0.5;
  filter: alpha(opacity = 50);
}

<!-- Le HTML correspondant -->
<header>
    <h1>Header Title</h1>
</header>
<footer>
    <h1>Small title in the footer</h1>
</footer>

Là encore, échec : on duplique du code inutilement, probablement sans même s’en rendre compte.

Les éléments déclarés ici ne sont tout simplement pas réutilisables, ils dépendent directement du conteneur dans lequel on les a défini. Or il apparaît clairement que certaines propriétés ne sont pas simplement spécifiques à ces conteneurs.

Ainsi, on devrait plutôt envisager l’alternative suivante :

h1 {
  font-family: 'Roboto', Helvetica, sans-serif;

  color: #f44;
}

/* … */

h1,
.h1-size {
  font-size: 2em;
}
h2,
.h2-size {
  font-size: 1.8em;
}
h3,
.h3-size {
  font-size: 1.5em;
}

/* … */

.muted {
  opacity: 0.5;
  filter: alpha(opacity = 50);
}

<!-- Le HTML correspondant -->
<header>
    <h1>Header Title</h1>
</header>
<footer>
    <h1 class="h3-size muted">Small title in the footer</h1>
</footer>

Ici vous me direz : “Bah, à quoi bon s’embêter avec ça ? On a pas vraiment gagné de place dans le code pour le coup !”. Et oui, pour le coup, c’est vrai… sur cet exemple particulier où l’on ne se concentre que sur le titre.

Mais l’OOCSS vous oblige à penser bien plus en amont les possibilités d’évolution de votre site. Ici, je n’ai pas simplement amélioré la flexibilité de mes titres, j’ai également introduit de nouveaux éléments :

Chaque niveau de titre à une font-size standard, homogène. Mais chacune de ces font-size est affecté dans le même temps à une classe afin de pouvoir être réutilisé indépendamment du contexte.

Vous noterez qu’en faisant cela je me préserve de tomber dans la mauvaise pratique (bouh !) qui consiste à choisir le niveau de titre en fonction de la taille que je veux donner visuellement à mon élément : c’est bon pour ma sémantique, c’est bon pour mon accessibilité et c’est bon pour ma SEO \o/
J’ai créé l’élément .muted qui me permet d’atténuer la visibilité (opacité) d’un élément. Je gage que cette petite classe utilitaire pourra me reservir ça et là à l’avenir et je suis sûr que je n’irais pas dupliquer le code un peu partout dans mon CSS.

Le media object

L’exemple le plus célèbre pour illustrer l’OOCSS est bien entendu le media object créé par Nicole Sullivan et qui permet d’économiser des centaines de lignes de code.

Il s’agit ni plus ni moins de l’objet abstrait pour représenter un media object (une image, une vidéo) à côté d’un media body (texte typiquement), à gauche comme à droite.

C’est un schéma typique qui tend à se répéter, le meilleur exemple qu’il soit étant Facebook notamment.

Voici basiquement en quoi le module consiste :

.media,
.media-body {
  overflow: hidden;
}
.media-img {
  float: left;
  margin-right: 20px;
}
.media-img-rev {
  float: right;
  margin-left: 20px;
}
.media-img img {
  display: block;
}

<!-- Structure du media object de base -->
<div class="media">
    <a href="#" class="media-img">
        <img src="#" alt="#">
    </a>
    <div class="media-body">
        <p>
            Lorem ipsum dolor sit amet, consectetur adipisicing elit.
        </p>
    </div>
</div>

Ces quelques lignes de CSS, réutilisables à souhait, génère un gain de temps et de performance considérable sur l’ensemble d’un projet.

Je ne saurais que trop vous conseiller de jeter un oeil au court article de Nicole que je vous ai indiqué précédemment. D’ailleurs je le remet, vous n’aurez pas d’excuse !

Notez par exemple que Bootstrap l’a implémenté, de même que inuit.css ce qui n’est pas étonnant sachant que ces deux frameworks se basent sur le concept de l’OOCSS.

Harry Roberts a récemment proposé le flag object qui reprend ni plus ni moins le media object avec la notion de centrage vertical en bonus, ce qui peut servir à certaines occasions.

Implémenter l’OOCSS dans son projet

Avant tout, il s’agit de bien comprendre et adhérer à la philosophie. Il n’y a pas de règles absolue et les bonnes pratiques changent à mesure que le web se développe et évolue. De plus, il faut toujours considérer le contexte du projet et définir ce qui est bon pour vous.

Cela étant, l’on peut synthétiser la mise en place d’un esprit OOCSS par quelques pratiques concrètes :

N’utilisez pas d’ID dans le CSS
Ne spécifiez pas vos sélecteurs (.error et pas p.error), sauf pour surcharger
Évitez au maximum l’utilisation de !important
Distinguer les composants de votre projet et faîtes en des modules
Si c’est pertinent, adoptez un framework CSS qui se base sur l’OOCSS. Je vous conseillerais Bootstrap si vous avez besoin d’un design pré-conçu ; inuit.css si seule la structure vous suffit (vous vous occupez de l’apparence, principe #1). Notez qu’il existe le framework oocss de Nicole Sullivan comme référence.

Quelques remarques

Bonnes remarques et fausses idées

Il va sans dire que cette manière de voir les choses n’est pas absolue et suscite débats.

Voici cependant quelques points qu’il convient de noter :

Il est tout à fait possible d’utiliser des ID dans le HTML, pour le Javascript notamment. De plus, les identifiants pourraient également se révéler intéressants en guise de namespace pour un module particulier que l’on partagerait, afin de ne pas causer de conflit potentiel.
Une des réticences à l’encontre de l’OOCSS rélève du fait que le HTML se retrouve “pollué” par un nombre conséquent de classes, ce qui fait rechigner les puristes. Il s’agit d’une appréciation personnelle de ce qu’est le juste milieu et cela se fait dans le choix de niveau d’abstraction. Cela étant, l’OOCSS n’impacte en rien la sémantique du HTML.
Les principes de l’OOCSS font des miracles du côté des gros projets où le jeu vaut vraiment la chandelle. Pour des petits projets (le site vitrine d’une association par exemple), it’s up to you! Cependant, la philosophie s’adpate quelque soit la taille du projet et ne demande pas plus de temps à être mise en place qu’un développement ordinaire une fois que vous commencez à vous faire la main dessus. Au contraire, les modules que vous avez créé pour tel ou tel autre projet peuvent tout autant vous resservir tels quels, il n’y a qu’à les rhabiller.

Bien que l’OOCSS soit une vision plutôt bien répandue par les bienfaits qu’elle apporte, je dois dire que moi j’étais perplexe en lisant ZE phrase choc : “avoid the use of ID in CSS, ever”.

Mais depuis que j’ai compris l’intérêt de cette pratique je la recommande chaudement.

Cela étant, ayant également adopté SMACSS dans l’organisation de mon code, j’utilise les identifiants dans mon CSS à un seul et unique endroit : le layout.

Tout est donc question d’adapter ce qui convient à son projet et sa philosophie.

Une autre philosophie

Une autre vision du CSS consiste au contraire dans une importance accordée au contexte où se situent les éléments.

C’est une autre philosophie, “interface-oriented” qui pose comme principe que le CSS vient styliser l’interface HTML existante. Il n’y a pas lieu de venir polluer le HTML avec des classes alors que les sélecteurs et une bonne organisation du code peuvent tout aussi bien intervenir sur le design.

Bien que je n’adhère pas à cette pratique (du moins pour tout projet susceptible de prendre de l’ampleur), elle est néamoins intéressante et n’en reste pas moins pertinente, dans le cas de petits projets par exemple.

Pour aller plus loin

Articles et liens intéressants

Voici une série de liens auxquels je vous suggère de jeter un oeil si vous souhaitez approfondir ma présentation :

An introduction to OOCSS, article introductif sur le concept par Smashing Magazine.
The OOCSS perspective par Nicole Sullivan, ou bien la version courte si vous n’êtes pas téméraires.
Liste des articles OOCSS sur le blog de Nicole Sullivan (oui, toujours elle, il faut rendre à César ce qui est à César).
Breaking Good Habits, speech de Harry Robert’s sur la question dont voici les slides.
OOCSS & RWD pour une petite réflexion sur comment l’OOCSS contribue à réaliser des sites web responsive et consistants.
Le CSS Orienté Objet expliqué avec Monsieur Patate, parce-que oui il y a quand même quelques articles français sur la question qui trainent sur le web.
CSSLint est un outil permettant de confronter votre CSS aux principes de OOCSS et de le corriger en ce sens.

Conclusion

Notre petite plongée au coeur de l’OOCSS s’achève ici.

Vous remarquerez que la très grande majorité des articles/sujets portant sur ces pratiques avancées de CSS sont en anglais, ce qui peut s’expliquer notamment par le fait que le sujet est encore récent (2009 pour les prémices, en pleine popularisation depuis le développement des frameworks CSS). Ce fut d’ailleurs la raison pour laquelle j’ai souhaité apporter ma pierre à l’édifice en rédigeant cet article en français.

J’espère que le sujet aura pu vous faire réfléchir sur vos pratiques CSS, voire même vous intéresser. Si vous avez des questions, des remarques, des suggestions ou même des idées à partager avec moi, n’hésitez pas à me laisser quelques commentaires ci-dessous =)

Vous aussi, adoptez le "Oh Oh" CSS

Plop !

Dive into OOCSS principles

Wed, 08 May 2013 00:00:00 GMT

I can haz OOCSS?

Consider a new web project: a start-up dreams of developing THE indispensable webapplication of tomorrow’s web. They choose wisefully technologies, frameworks, environments they’ll use… However, the front-end rendering will still the same for the browser: HTML, CSS and Javascript.

But here’s the thing: even if the whole application will probably take advantages of some frameworks, have a look over the stylesheet and you’ll probably get something like that, with or without preprocessor:

#form-generator {
  width: 760px;
  margin: auto;
}

#form-generator label {
  font-weight: bold;
  font-size: 12px;
  /* … */
}

#form-generator label.title {
  font-weight: normal;
  font-size: 11px;
  /* … */
}

#form-generator textarea {
  width: 350px;
}

#form-generator .big textarea {
  width: 500px;
}

/* a bunch of CSS */

This kind of code will cause a lot of hassles over time:

Lack of flexibility, it can only apply to elements which are contained in the form which gets the #form-generator identifier. That could sound relevant at first, but what if you want to build other pages with some similars forms in it?
Too much specificity, you have to overspecified again and again selectors when you want to create some particular cases. Just look at label.title-titre or .big textarea for instance.
Too complicated, you need to be an expert and know the architecture of every single page to dissect and maintain all of this mess. Plus, it would probably grow as the project develops.

If you add some messy organisation for CSS files, then you get a spaghetti code which would lead to a lot of troubles, errors, code duplication as new developers enters the ring over time.

This extreme dependency between the HTML structure makes the code be especially fragile: even if it’s clean, a simple mistake of a non-expert can ruined it completely.

In short, these non-mature practices will make things harder for the start-up and promises long sleepless nights of debug and refactor.

Finally, the problem here belongs to the 1:1 relation between CSS and the number of blocks, pages, modules of the website. As long as it grows, the stylesheet grows as well. That implies development time, and so money… We could do better in terms of ROI.

Freely inspired by Jonathan Snoovvk =)

The Object Oriented CSS (OOCSS) bring its own solution to these problems. It’s nor a new preprocessor, nor a new language, but a code philosophy. It’s a set of best practices, rules and advices to help your CSS become scalable.

OOCSS has 2 principles :

Separate structure from skin
Separate container from content

1. Separate structure from skin

Usually, elements of a website have a visual aspect which is repeated in different contexts : colors, font, borders, … the graphic charter in a whole. This is the skin.

In the same time, a bunch of “non-visible” properties are repeated : width/height, overflow, etc. This is the structure.

If you separate them, you create re-usable components that can be shared into elements which have same properties. And so we speak about objects, which may sound familiar to back-end developers by the way.

2. Separate container from content

The deal here is not to stupidly constrain the style of an element (the content) to the its context (its container).

If you are designing titles, why limit yourself to those who are into the <header>, just because this is the only title place for now? Plus, it’s very likely that all your titles have a consistent design in your whole website for ergonomics concerns.

It’s even more true for modules.

Why is OOCSS good?

The 10 best practices

Here are the 10 best practices that are part of the OOCSS spirit:

Create a library per component
Each component - button, table, link, image, clearfix, etc. - should be a piece of Lego = combinable and re-usable as you wish.
Use semantic and consistent styles
The style of a new HTML element should be predictable.
Design transparent modules
The module is the container that could be used with any content.
Be flexible
Height and width should be extensible and adapt themself - RWD inside -.
Learn to love grids
Grids allow you to control width. Height is generally defined by the content.
Minimize selectors
Keep a low specificity [0-0-1-0] to have a better control over selectors.
Separate structure from skin
You must do the distinction, it’s a fundamental principle of OOCSS. Create abstract objects for blocks structure and use class to dress these blocks, regardless their nature.
Separate container from content
You must do the distinction, it’s a fundamental principle of OOCSS. Create 1:n relationship separating the container from its content.
Extend objects with multiple classes Class/objects are just like Legos you put together to build the expected result.
Use resets and YUI fonts
This is a specific choice of the OOCSS framework.

Legos first - A best practice is to design individual pages after having created basic components for the whole website.

The 9 pitfalls to avoid

Here are the 9 pitfalls to ban, according to the OOCSS spirit:

Create styles that depend on context
There is nothing less flexible but a article > p:nth-child(2) > span.plop selector.
Overspecify selectors
div.my-class is uselessly overspecific as .my-class is sufficient enough. However, it becomes relevant if you want to override a class styling for some specific elements - strong.error will override the defaults rules of .error for this special use -.
Use IDs
What an ID can do, a class can do better. Futhermore, IDs contribute in creating unexpected specificity mess.
Use shadows and border-radius on irregular backgrounds
It could have unexpected results.
Create a sprite containing every images, excepted if you don’t have a lot of pages
It’s not very optimal in certain cases as you need to deal with image rendering exclusively in CSS.
Precisely adjust the height
An element height is controlled by its content. Separate container from content will make your life easier.
Use images as texts
I guess you can reach a better accessibility level.
Be redundant
Two components which that look too close to be differenciate on a same page look too close to be used on the website: choose one!
Do early optimisation
Developers tend to waste a lot of time on the optimisation question when it’s not critical than to focus on what is essential to go on.

OOCSS benefits

As the project is going on, you will be able to create whole new pages combining existing elements without adding any CSS, even for a completely new architecture.

Re-use elements is also a totally free performance gain! You’ll create new elements with 0 line of CSS code, what could be better?

OOCSS force you to think the website as a whole instead of focusing on simple pages put one along the others. You should anticipate the future.

Finally, the main advantage of this philosophy IMHO is that it makes your CSS modular, easier to maintain. This modularity makes your CSS robust: a new developer would be less likely to break the design when working on it.

OOCSS, how does that works?

Gimme concrete examples!

Remember the 2 main principles:

Separate structure from skin
Separate container from content

With these good practices in mind, let’s see how to apply the philosophy on a daily code.

1. Separate structure from skin

Let’s take the favorite example over blog posts: buttons. A “classic” CSS would look like this, I guess:

#button {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

#button-primary {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #ffffff;
  text-align: center;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  vertical-align: middle;
  cursor: pointer;

  background-color: #006dcc;
}

#button-large {
  display: inline-block;
  padding: 8px 16px;
  margin-bottom: 0;

  font-size: 18px;
  line-height: 28px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

#button-activation {
  display: inline-block;
  padding: 8px 16px;
  margin-bottom: 0;

  font-size: 18px;
  line-height: 28px;
  color: #ffffff;
  text-align: center;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  vertical-align: middle;
  cursor: pointer;

  background-color: #006dcc;
}

<!-- The corresponding HTML -->

<a href="#" id="button">Default</a>
<a href="#" id="button-primary">Primary</a>
<a href="#" id="button-large">Large</a>
<a href="#" id="button-activation">Large Primary</a>

In the end, you come with a lot of redundancy and a #button-activation which is nothing but a large version of #botton-primary.

If you refactor this CSS with OOCSS principles, you’ll get something more flexible:

.button {
  display: inline-block;
  padding: 4px 12px;
  margin-bottom: 0;

  font-size: 14px;
  line-height: 20px;
  color: #333333;
  text-align: center;

  vertical-align: middle;
  cursor: pointer;

  background-color: #d5d5d5;
}

.button-primary {
  color: #ffffff;
  text-shadow: 0 -1px 0 rgba(0, 0, 0, 0.25);

  background-color: #006dcc;
}

.button-large {
  padding: 8px 16px;

  font-size: 18px;
  line-height: 28px;
}

<!-- The corresponding HTML -->

<a href="#" class="button">Default</a>
<a href="#" class="button button-primary">Primary</a>
<a href="#" class="button button-large">Large</a>
<a href="#" class="button button-large button-primary">Large Primary</a>

.button define the generic properties - the “defaults” ones - for our buttons. If you override it, you come with new classes that you can combine to get the expected result, just like Legos!

Here was the trick.

2. Separate container from content

It did happen, sometimes, that my code looked like this when developing the main design:

header h1 {
  font-family: 'Roboto', Helvetica, sans-serif;
  font-size: 2em;

  color: #f44;
}

/* a bunch of CSS */

footer h1 {
  font-family: 'Roboto', Helvetica, sans-serif;
  font-size: 1.5em;

  color: #f44;
  opacity: 0.5;
  filter: alpha(opacity = 50);
}

<!-- The corresponding HTML -->

<header>
  <h1>Header Title</h1>
</header>
<footer>
  <h1>Small title in the footer</h1>
</footer>

Here again, it’s a fail: I am duplicating code, which is useless and I didn’t even notice that!

The elements I defined here are simply not re-usable. They directly rely on a specific container. But it’s clear enough that some properties are not specific to this container.

And so I may have consider the following alternative:

h1 {
  font-family: 'Roboto', Helvetica, sans-serif;

  color: #f44;
}

/* … */
h1,
.h1-size {
  font-size: 2em;
}

h2,
.h2-size {
  font-size: 1.8em;
}

h3,
.h3-size {
  font-size: 1.5em;
}

/* … */
.muted {
  opacity: 0.5;
  filter: alpha(opacity = 50);
}

<!-- The corresponding HTML -->

<header>
  <h1>Header Title</h1>
</header>
<footer>
  <h1 class="h3-size muted">Small title in the footer</h1>
</footer>

You may think “Why should I care? We don’t really reduce code here!“. For sure that’s true here… if you only focus on the title.

But OOCSS makes you think further about the future of your website. Here we don’t just improved titles flexibility, but we add few new elements:

Each level of title has a standard and homogene font-size. Each of these font-size is also set to an independent class and could be re-used, whatever the context

Doing so, you’ll notice that I didn’t choose the level of title because of the default sizing it would render on the screen: it’s better for semantics, for accessibility and SEO \o/
I created a .muted class that allows me to mitigate the visibility/opacity of an element. I guess this little utility would be useful later and I’m sure I won’t have to duplicate that kind of code around in my CSS.

The media object

The most famous example which illustrate OOCSS is the media object created by Nicole Sullivan. It saves hundreds of lines of code.

It’s nothing but an abstract object which represents a media object - a picture, a video - aside to a media body - typically a text -, to its left or to its right.

It’s a typical scheme that is repeated everywhere. Think about the Facebook display.

Here is basically the module content:

.media,
.media-body {
  overflow: hidden;
}

.media-img {
  float: left;
  margin-right: 20px;
}

.media-img-rev {
  float: right;
  margin-left: 20px;
}

.media-img img {
  display: block;
}

<!-- Base structure for the media object -->

<div class="media">
  <a href="#" class="media-img">
    <img src="#" alt="#">
  </a>
  <div class="media-body">
    <p>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit.
    </p>
  </div>
</div>

These few re-usable lines of CSS will save a lot of time and help to improve performance over a whole project.

You’ll note that Bootstrap has implemented it, just like inuit.css, which is not that surprising when you consider these two frameworks use OOCSS concepts.

Harry Roberts has recently proposed the flag object which incorporates more or less the media object with the vertical centering concept.

Implement the OOCSS in your project

First of all, you need to understand and adhere to the philosophy. There is no absolute rule and best practices change as the web develop and evolve. Plus, you should always consider the context of your project and define what is good for you.

That said, we can sum up the implementation of an OOCSS spirit with some concrete practices:

Don’t use IDs for CSS
Don’t overspecify your selectors (.error and not p.error), excepted for overriding reasons
Avoid the use of !important
Distinguish components of your project and create modules out of them
If relevant, adopt a CSS framework based over OOCSS principles. I’d advice you to use Bootstrap if you need a predefined design ; inuit.css is you just need about structure and deal with the design by yourself. Note that the oocss framework from Nicole Sullivan exists as a reference.

Few comments

Good remarks and poor ideas

No need to say that these philosophy is a non-absolute vision of CSS that we could debate on.

However, we can point out the following things:

It’s absolutely possible to use IDs in HTML for JavaScript purpose, for instance. Moreover, identifiers could be useful as namespaces for a particular module that you want to share without breaking anything.
One of the arguments against OOCSS is that you are “polluting” HTML with a bunch of classes that some HTML-evangelist don’t appreciate, which is understandable. However, OOCSS doesn’t impact the HTML semantics.
OOCSS principles can perform miracles over big projects, where it worth to implement them. For little ones, it’s up to you! However, the philosophy is relevant regardless the size of your project and doesn’t take that long to be implemented than an ordinary development when you get used to it. Rather, modules you’ve already created for any other project could be re-used in a new one, you just have to change their design a bit and there you go!

Even if OOCSS is now a well-spread vision for the benefits it brings, I must say that I was suspicious when I read the assertion: “avoid the use of ID in CSS, ever”.

But since I understood the benefits of this practice, I warmly recommend it.

That said, as I get smacked for my code organisation, I now use IDs in my CSS in a unique place : the layout.

It’s just a matter of adaptation to your project needs and philosophy.

Another philosophy

Another vision of CSS give its importance to the context of elements.

It’s another philosophy, interface-oriented which considers that CSS is defined to design the existing HTML interface. To pollute HTML with classes is a non-sense when selectors and good code organisation can deal with the design.

Even though I don’t adhere to this practice - at least for a project which is meant to evolve -, it’s an interesting philosophy which could be relevant for small projects, for instance.

To go further

Posts and interesting links

Here is a list of links you may have a look to go deeper into OOCSS:

An introduction to OOCSS, is an introducting post about this concept, by Smashing Magazine.
The OOCSS perspective by Nicole Sullivan, or even the short version if you don’t have time.
List of Nicole Sullivan’s blog post about OOCSS.
Breaking Good Habits, speech from Harry Robert with the according slides.
OOCSS & RWD to think about how the OOCSS can help to build responsive websites.
CSSLint is a tool that will lint your CSS according to OOCSS principles.

Conclusion

Our little dive into OOCSS is now over.

Adopt the "Oh Oh" CSS

Plop!

jQuery, data et performance

Sat, 04 May 2013 00:00:00 GMT

TL;DR

jQuery simplifie la manipulation des données rattachées aux éléments.

L’attribut HTML5 data-* est lié à l’objet data de jQuery pour les éléments du DOM.

$.data(element, key[, value]) permet de manipuler des données rattachées aux éléments du DOM.

$.fn.data(key[, value]) permet de manipuler des données rattachées aux éléments jQuery.

$.data étant plus basique que $.fn.data, il est plus rapide à l’exécution. Il est en revanche moins flexible, moins pratique et il ne permet pas d’accéder aux attributs data-*.

<!-- HTML -->
<div id="main-content"></div>

// Javascript
var $el = $('#main-content')

$el.data('key', 'plop') // rapide
$.data($el, 'key', 'plop') // 10 fois plus rapide

Enfin, ces 2 méthodes ne modifient pas le DOM, contrairement à $.fn.attr.

$el.data('key', 'plop')
// <div id="main-content"></div>
$.data($el, 'key', 'plop')
// <div id="main-content"></div>
$el.attr('data-key', 'plop')
// <div id="main-content" data-key="plop"></div>

Manipuler des data avec jQuery

Rattacher une information à un élément et la manipuler au fil de l’exécution d’un script est une opération vraiment simple avec jQuery. En effet, la bibliothèque dispose de méthodes permettant de stocker, modifier et supprimer les données relatives à un élément.

Par ailleurs, il est intéressant de savoir que les attributs data-* introduits par le HTML5 sont automatiquement transformés en objet data jQuery et sont donc accessibles par le biais de certaines de ces méthodes.

$.fn.data

La méthode la plus populaire est $.fn.data qui s’utilise de la manière suivante :

// Affecte la chaîne de caractère "plop" à la clef "key"
elem.data('key', 'plop')

// Lit la donnée portant la clef "key"
elem.data('key')

<!-- Code valide en HTML5 -->
<div id="elem" data-my-key="hey"></div>

$('#elem').data('myKey') // Retourne "hey"

Vous noterez que l’on retire data- et l’on supprime les tirets du HTML pour spécifier la clef, avec une notation à la CamelCase conformément à la spécification W3C.

La documentation est simple à assimiler et présente plutôt bien le concept.

Notez que l’on dispose également de la méthode $.fn.removeData pour nettoyer tout cela si besoin :

elem.removeData('key') // Bye bye !

$.data

Il existe également la méthode jQuery $.data plus bas-niveau, moins connue. Elle remplie quasiment le même rôle, à ceci près que sa syntaxe diffère et qu’elle considère l’élément du DOM associé en paramètre.

// Affecte la chaîne de caractère "plop" à la clef "key"
$.data(elem, 'key', 'plop')

// Lit la donnée portant la clef "key"
$.data(elem, 'key')

Là encore, je vous invite à jeter un oeil à la documentation officielle.

L’on dispose également de la méthode $.removeData pour supprimer des données, ainsi que de la méthode $.hasData pour vérifier si l’élément a des données rattachées ou non :

$.hasData(elem) // Retourne "true"
$.removeData(elem, 'key') // Bye bye !
$.hasData(elem) // Retourne "false"

Performance vs. Puissance

Quel est l’intérêt d’utiliser $.data quand $.fn.data est plus sexy me direz-vous ?

Et bien comme la méthode est plus bas-niveau, plus simple, elle s’exécute aussi bien plus rapidement !

el.data('key', 'plop') // rapide
$.data(el, 'key', 'plop') // jusqu'à 10 fois plus rapide

Je vous invite à tester les performances par vous-même.

En contrepartie, elle doit rattacher les données à un élément du DOM tandis que $.fn.data peut gérer des données sur toute sorte d’objet jQuery, y compris les évènements :

// Affecte l'index de chaque lien comme donnée de l'événement "click"
// Quand on clique sur un lien, ça affiche son index
$('a').each(function(i) {
  $(this).on('click', { index: i }, function(e) {
    alert('Mon index est ' + e.data.index)
  })
})

Enfin, $.data ne gère pas les attributs HTML5 data-* tandis que $.fn.data si.

En pratique :

si l’on travaille avec un événement, on utilise $.fn.data
si l’on travaille avec un attribut HTML5 data-*, on utilise $.fn.data
dans tous les autres cas, on utilise $.data parce-qu’il est plus performant

Un mot sur le DOM

Il est bon de noter que les deux méthodes $.data et $.fn.data ont ceci en commun qu’elles ne modifient pas le DOM.

Plus concrètement, si la méthode $.fn.data permet d’accéder aux attributs data-*, elle ne les modifiera pas (pas dans le DOM). En effet, il ne faut pas se laisser embrouiller par le niveau d’abstraction de la fonction : ce n’est pas l’attribut que vous manipulez par cette méthode mais un objet jQuery, créé automatiquement pour l’occasion.

En contrepartie, la méthode $.fn.attr est une alternative qui permet d’accéder aux attributs du DOM ainsi que de les modifier.

<div id="main-content" data-my-key="hey"></div>

$('#main-content').data('myKey', 'plop')
// Change l'objet jQuery mais ne change pas le DOM
// <div id="main-content" data-my-key="hey"></div>
// Rq: $('#main-content').data('myKey') retourne bien "plop"

$('#main-content').attr('data-my-key', 'plop')
// Change effectivement le DOM
// <div id="main-content" data-key="plop"></div>

Dans le premier cas, nous avons bel et bien modifié l’objet jQuery, mais aucune opération n’est menée sur le HTML.

Dans le second cas en revanche, c’est bel et bien le HTML que l’on modifie.

En ce qui concerne la performance, il est à noter que le second est plus rapide que le premier. Une raison à cela est probablement que $.fn.data fait bien plus que juste “accéder” à l’élément : il le caste en fonction de son type.

Ainsi, cela peut être assez utile pour l’élaboration de plugins ou de widgets :

<div class="widget" data-row="2" data-responsive="true"></div>

$('.widget').each(function() {
  $(this).myWidget($(this).data('rows'), $(this).data('responsive'))
})

En contrepartie, $.fn.attr renverra toujours une chaîne de caractères, ce qui peut être utile dans certains cas.

Le mot de la fin

Voici pour une brève (mais intense !) présentation des méthodes qui existent en jQuery pour manipuler les données.

Le point sur la performance me semblait intéressant, il ne faut pas se formaliser pour autant : ce n’est pas cela qui boostera considérablement vos scripts. Cela étant, c’est toujours bon à savoir !

Avec un peu de chance, cela aura été l’un de vos “Aha moment” en JS (comme diraient certains) =)

Plop !

jQuery, data and performance

Sat, 04 May 2013 00:00:00 GMT

TL;DR

jQuery makes elements-related data manipulation easy.

The HTML5 data-* attribute is linked in some way to the jQuery data object for DOM elements.

$.data(element, key[, value]) deals with DOM elements related data.

$.fn.data(key[, value]) deals with jQuery elements related data.

$.data is low-level and executes faster while $.fn.data is much more convenient and flexible. Futhermore, the second one can access to the data-* attributes.

<!-- HTML -->
<div id="main-content"></div>

// Javascript
var $el = $('#main-content')

$el.data('key', 'plop') // fast
$.data($el, 'key', 'plop') // 10 times faster

Finally, unlike $.fn.attr, both of these methods don’t modify the DOM.

$el.data('key', 'plop')
// <div id="main-content"></div>
$.data($el, 'key', 'plop')
// <div id="main-content"></div>
$el.attr('data-key', 'plop')
// <div id="main-content" data-key="plop"></div>

Data manipulation with jQuery

To attach an information to an element and manipulate it over script execution is dead easy with jQuery. Indeed, the library has methods to store, modify and delete data which are related to an element.

Futhermore, it’s good to know that the data-* attributes introduced with HTML5 are automatically pulled as a jQuery data object. Doing so, they are accessible through some of its methods.

$.fn.data

The most popular method is $.fn.data which is used as below:

// Affects the "plop" string to the "key" key
elem.data('key', 'plop')

// Reads the data with the "key" key
elem.data('key')

<!-- Valid HTML5 code -->
<div id="elem" data-my-key="hey"></div>

$('#elem').data('myKey') // Outputs "hey"

You’ll notice that we remove data- and the HTML hyphens to specify the key the CamelCase way, accordingly to the W3C specification.

The documentation is very simple to get in and gives a good overview of the concept.

But wait there’s more… use the $.fn.removeData method to clean all that mess:

elem.removeData('key') // Bye!

$.data

The library also comes with a more low-level and less known method, $.data. It plays the same role excepted the syntax and the fact that you need to provide a DOM element associated to the data as a parameter.

// Affects the "plop" string to the "key" key
$.data(elem, 'key', 'plop')

// Reads the data with the "key" key
$.data(elem, 'key')

Here again, please have a look to the official documentation.

We also get the $.removeData method to remove data and the $.hasData one to check if an element does or doesn’t have data attached:

$.hasData(elem) // Outputs "true"
$.removeData(elem, 'key') // Bye!
$.hasData(elem) // Outputs "false"

Performance vs. Power

Why should I use $.data when $.fn.data is much more sexy to write?

Well, as the method is low-level, it goes way faster!

el.data('key', 'plop') // fast
$.data(el, 'key', 'plop') // up to 10 times faster

I invite you to test performances by yourself.

The other side of the coin is that it should attach data to a DOM element while $.fn.data can handle any sort of jQuery object, events included:

// Affects each link index as a data for the "click" event
// When you click on a link, it shows its index
$('a').each(function(i) {
  $(this).on('click', { index: i }, function(e) {
    alert('My index is ' + e.data.index)
  })
})

Finally, $.data doesn’t manage HTML5 data-* attributes while $.fn.data does.

Concretely:

if you deal with an event, use $.fn.data
if you deal with an HTML5 data-* attribute, use $.fn.data
otherwise, use $.data because of performance

A word about the DOM

It’s also good to know that both of the $.data and $.fn.data methods do not modify the DOM.

More precisely, although the $.fn.data methods can access to data-* attributes, it wouldn’t modify them in the DOM. You shouldn’t get tricked because of the function abstraction: it’s not the attribute you are manipulating but an automatically created jQuery object.

In return, the $.fn.attr method is an alternative to reach DOM attributes and to modify them.

<div id="main-content" data-my-key="hey"></div>

$('#main-content').data('myKey', 'plop')
// Change the jQuery object, not the DOM
// <div id="main-content" data-my-key="hey"></div>
// Note: $('#main-content').data('myKey') outputs "plop"

$('#main-content').attr('data-my-key', 'plop')
// Change effectively the DOM
// <div id="main-content" data-key="plop"></div>

In the first code, we modified the jQuery object but nothing happen on the HTML.

In the second code however, we concretely modified the HTML.

Concerning performance, you might note that the second is way faster than the first one. A reason for that would probably be that $.fn.data does more than just “reach” the element: it performs some casting regarding to the type of the element.

Thus, it could be very helpful for plugins or widgets initialization:

<div class="widget" data-row="2" data-responsive="true"></div>

$('.widget').each(function() {
  $(this).myWidget($(this).data('rows'), $(this).data('responsive'))
})

On the other hand, $.fn.attr will always output a string, which could be necessary sometimes.

Last words

That’s it for my short (but intense!) presentation of existing jQuery methods to manipulate data.

I thought that notes about performance would have been interesting, but it shouldn’t be a concern: this is not what would make you script significantly faster. Still, it’s good to know about it!

If I’m lucky enough, that may have been one of your “Aha moment” with JS (as some people would call that) =)

Plop!

Optimiser ses sélecteurs, CSS vs. JS

Thu, 02 May 2013 00:00:00 GMT

TL;DR

Les sélecteurs sont interprétés de la droite vers la gauche.

En CSS, il est préférable d’utiliser une classe plutôt qu’un identifiant dans la mesure où le premier fait tout aussi bien que le second et même plus. L’idée est de garder la spécificité du sélecteur la plus basse possible pour simplifier la maintenabilité du code.

En JS, un identifiant et une spécificité accrue donnera de meilleurs résultats en terme de performance. Il s’agit d’aller droit au but. Inutile cependant d’être trop spécifique, c’est contre-productif.

Évitez d’utiliser le sélecteur universel * dans une chaîne de sélecteurs.

Les deux pratiques ne sont pas incompatibles et n’empêchent pas votre HTML d’être sémantique :

<!-- HTML -->
<article id="main-article">
    <!-- … -->
    <ol role="navigation" class="nav nav--block pagination">
        <li class="pagination__prev">
            <a href="/page1">&lt; Previous</a>
        </li>
        <li class="pagination__next">
            <a href="/page3">Next &gt;</a>
        </li>
    </ol>
</article>

/* CSS */
.nav {
  list-style: none;
  margin-left: 0;
}

.nav--block {
  line-height: 1;
}

/* Mauvaise idée */
.nav--block * {
  color: red;
}

/* Pas de gros soucis */
* {
  box-sizing: border-box;
}

// Javascript (jQuery)
$('#main-article .nav--block .pagination__prev') // fast
$('#main-article .nav--block li.pagination__prev') // faster
$('#main-article').find('.pagination__prev') // super-fast

En CSS

Ce qui va suivre relève de bonnes pratiques CSS connues sous le nom d’OOCSS (Object Oriented CSS). C’est une philosophie assez répandue et à laquelle j’adhère, mais ce n’est pas la seule façon de voir les choses. Je crois cependant qu’elle s’adapte à tout type de projets, grands ou petits, avec l’avantage d’être future-proof.

Voici une introduction à ses principes, pour ceux que ça intéresse, ainsi qu’une vision alternative (que je ne partage pas, mais qui a sa légitimité selon moi). Libre à chacun de suivre sa voie.

Class ou ID ?

Pour faire bref, du point de vue du CSS une classe peut faire tout ce que fait un identifiant mais un identifiant ne peut pas être réutilisé.

Partant de ce constat, l’usage d’une classe peut facilement se substituer à celui d’un identifiant et permet d’anticiper sur l’avenir.

De plus, un identifiant augmente considérablement la spécificité de la déclaration, ce qui peut vite entraîner un joli bordel au fil du temps, et une utilisation inappropriée de !important ou autre déclarations de style inline, directement dans le HTML, pour surcharger le style désiré. Autrement dit, c’est pas joli à voir !

<!-- Pas très future-proof -->
<ol id="pagination">
    <li>
        <a href="/page1">&lt; Previous</a>
    </li>
    <li>
        <a href="/page3">Next &gt;</a>
    </li>
</ol>

#pagination {
  list-style: none;
  margin-left: 0;
  line-height: 1;
}

Quid si demain apparaît un autre type de pagination sur un module de la page ? On crée un nouvel identifiant avec un autre nom et peu ou prou les mêmes propriétés ? Et puis, la pagination n’est-elle pas une sorte de menu de navigation en soi ?

<!-- Future-proof -->
<ol class="nav pagination">
    <li>
        <a href="/page1">&lt; Previous</a>
    </li>
    <li>
        <a href="/page3">Next &gt;</a>
    </li>
</ol>

.nav {
  list-style: none;
  margin-left: 0;
}

.pagination {
  line-height: 1;
}

La classe .nav est d’ailleurs parfaitement réutilisable, c’est une couche d’abstraction qui détermine les propriétés communes à tous mes menus de type navigation sur mon site (à son pépère !).

Bewaaaaare la spécificité !

En CSS, les règles de spécificité sont plus ou moins simples, plus ou moins connues et engendrent plus ou moins de problèmes selon que l’on ait plus ou moins écrit son CSS intelligemment.

Pour faire bien, faisons simple : ne vous lancez pas dans des sélecteurs trop spécifiques qui alourdissent la règle inutilement.

Il s’agit de rester dans l’esprit OOCSS : les classes sont autant d’objets plus ou moins abstraits que l’on combine, tels des legos, pour produire le résultat attendu. C’est plus stable et maintenable dans le temps !

ol.nav {
} /* 0-0-1-1 spécification inutile */
article > .nav li a {
} /* 0-0-1-3 trop spécifique ! */
.pagination__prev {
} /* 0-0-1-0 OK */

L’idée est de produire un code CSS performant car :

non dépendant du contexte HTML dans lequel il se trouve (flexibilité)
pouvant être facilement surchargé (maintenabilité)
accessoirement, simple à concevoir

Un bon indicateur d’un CSS qui part en vrille réside dans le fait d’utiliser !important pour appliquer un style “parce-que sinon ça ne marche pas et konsaipapourkoi” !

Si les chiffres ne sont pas votre fort (et que vous n’aimez pas mon lien précédent et son dessin récapitulatif), voici un calculateur en ligne de spécificité CSS qui peut vous aider. L’idée est de garder une spécificité avoisinant [0-0-1-0] pour vos règles (l’équivalent d’une classe CSS), d’une manière générale. Ainsi, plus de perte de temps à investiguer pourquoi votre style ne s’applique pas.

En Javascript

N.B. - Javascript est un abus de langage ici dans la mesure où je parle de bibliothèques JS avec jQuery en référence.

Il convient cependant de noter qu’en termes de performances, le JS pur donnera de meilleurs résultats et document.getElementById() est probablement le plus performant.

Un(e) bon(ne) ID

L’identifiant est de loin le plus efficace des sélecteurs. Une fois que le moteur de sélection a trouvé l’élément, il arrête sa traversée du DOM. L’utilisation d’un identifiant est pertinente dans le cas du Javascript car l’on souhaite, la plupart du temps, travailler avec un élément bien précis, identifié.

En bref, il est bien plus efficace d’isoler l’identifiant dans le sélecteur, puis de chainer avec une fonction de recherche, afin de limiter le champ de recherche du moteur :

$('#main-article .pagination__prev') // rapide
$('#main-article').find('.pagination__prev') // 2 fois plus rapide

Dans le premier cas, le moteur va chercher l’ensemble des éléments dans le DOM portant la classe .pagination__prev, puis rechercher ceux qui se trouvent dans le bloc identifié par #main-article.

Dans le second cas, le moteur va d’abord rechercher le bloc #main-article, puis va chercher les éléments portant la classe .pagination__prev à l’intérieur de ce bloc.

Je vous invite à tester par vous-même les performances.

Spécifique mais pas trop

Il s’agit d’un petit point mais augmenter la spécificité à droite de votre sélecteur peut permettre à votre moteur d’aller plus vite dans sa recherche effectivement.

En revanche, inutile d’en faire des caisses : évitez d’alourdir inutilement votre sélecteur ou votre performance en pâtira.

$('ol.nav--block .muted') // non-optimisé
$('.nav--block li.pagination__next a.muted') // non-optimisé
$('.nav--block a.muted') // optimisé

Gare au sélecteur universel

MAJ le 4 Mai 2013 après une intéressante lecture sur l’utilisation de * en CSS et son impact sur la performance (le paragraphe sur la performance).

Que ce soit en CSS ou en JS, * peut devenir la bête noire des performances en terme de sélection.

Mal utilisé en CSS ou, sans le savoir, dans les sélecteurs JS, c’est ce qu’il peut y avoir de pire pour le moteur de sélection qui doit se coltiner tous les éléments du DOM.

Dans le cas du CSS, posez-vous la question : ais-je vraiment besoin de cibler tous les éléments, quels qu’ils soient ? La réponse sera probablement “non”.

Et n’allez pas croire que ceci est une bonne idée :

.nav--block * {
  color: red;
}

Car si vous lisez “dans les éléments .nav--block, tous les éléments”, le moteur lira “tous les éléments, puis ceux qui ont .nav--block comme parent”. De droite à gauche on vous dit !

En revanche, ceci ne posera pas de soucis de performance, à moins que vous en soyez à peaufiner votre score Page Speed au delà de 90 (autrement dit, c’est pas la priorité) :

/* apply a natural box layout model to all elements */
* {
  -moz-box-sizing: border-box;
  -webkit-box-sizing: border-box;
  box-sizing: border-box;
}

Dans le cas du JS, c’est encore plus fourbe car si vous ne faîtes pas attention, vous le suggérez par défaut. Enfin, il existe probablement des fonctions alternatives qui permettent d’arriver à exprimer ce que vous souhaitez faire.

$('.nav--block > *') // ouch !
$('.nav--block').children() // mieux

$('.form-fields :radio') // = $('.form-fields *:radio');
$('.form-fields input:radio') // mieux

Le mot de la fin

Voilà pour mon petit point de vue sur les sélecteurs.

Ce sont quelques bonnes pratiques que j’ai intégré avec le temps et qui sont ouvertes à la discussion ; n’hésitez pas à émettre des remarques, questions ou suggestions ci-dessous =)

Plop !

Optimize selectors, CSS vs. JS

Thu, 02 May 2013 00:00:00 GMT

TL;DR

Selectors are interpreted from right to left.

With CSS, it’s better to use a class instead of an identifier as the first one can do exactly the same than the second one, and more. You have to keep the specificity as low as possible to improve code scalability.

With JS, an identifier and an high specificity will lead to more efficient results. You’ve to go straight to the point. But it’s pointless to be over-specific, it’s counter-productive.

Don’t use the universal selector * in a selector chain.

Both are not mutually exclusive and do not prevent your HTML to be semantic:

<!-- HTML -->

<article id="main-article">
    <!-- … -->
  <ol role="navigation" class="nav nav--block pagination">
    <li class="pagination__prev">
      <a href="/page1">&lt; Previous</a>
    </li>
    <li class="pagination__next">
      <a href="/page3">Next &gt;</a>
    </li>
  </ol>
</article>

/* CSS */
.nav {
  list-style: none;
  margin-left: 0;
}

.nav--block {
  line-height: 1;
}

/* Bad idea */
.nav--block \* {
  color: red;
}

/* Not a big deal */
* {
  box-sizing: border-box;
}

// Javascript (jQuery)
$('#main-article .nav--block .pagination**prev') // fast
$('#main-article .nav--block li.pagination**prev') // faster
$('#main-article').find('.pagination__prev') // super-fast

With CSS

This come from CSS best practices known as OOCSS (Object Oriented CSS). It’s a fairly generalized philosophy I agree with, but it’s not the only way. However, I trust it could be used for any kind of project, regardless its size, with a future-proof argument.

Here is an introduction to OOCSS principles for those who are interested in. This is an alternative vision I don’t share but which is legit still. Feel free to follow your own path.

Class or ID ?

In short, from CSS point of view a class can do whatever an identifier does, but an identifier cannot be reused.

That said, we can use classes instead of identifier and anticipate the future.

Furthermore, an identifier considerably increase the declaration specificity. This will make your CSS a mess with inappropriate uses of !important or other inline style declarations directly within the HTML to override the desired style.

<!-- Not really future-proof -->

<ol id="pagination">
  <li>
    <a href="/page1">&lt; Previous</a>
  </li>
  <li>
    <a href="/page3">Next &gt;</a>
  </li>
</ol>

#pagination {
  list-style: none;
  margin-left: 0;
  line-height: 1;
}

What if another type of pagination appears somewhere else on the page? Do we create a completely new identifier with kind of the same properties? However, pagination sounds like some kind of navigation, doesn’t it?

<!-- Future-proof -->

<ol class="nav pagination">
  <li>
    <a href="/page1">&lt; Previous</a>
  </li>
  <li>
    <a href="/page3">Next &gt;</a>
  </li>
</ol>

.nav {
  list-style: none;
  margin-left: 0;
}

.pagination {
  line-height: 1;
}

The .nav class is perfectly reusable. It’s an abstract layer which determine the common properties to all the navigation menu of my website.

Bewaaaaare specificity!

With CSS, the specificity rules are more or less easy to figure out, more or less known and lead to more or less problems whether our CSS is more or less cleverly written.

In a few words: don’t write over-specified selectors which make rules unnecessarily heavy.

It’s about OOCSS spirit: classes are more or less abstracts objects you can combine as lego to produce the expected output. It’s much more stable and scalable over time!

ol.nav {
} /* 0-0-1-1 useless specification */
article > .nav li a {
} /* 0-0-1-3 too specific! */
.pagination__prev {
} /* 0-0-1-0 OK */

The deal is to produce an efficient CSS because:

it’s loosely coupled with the HTML context (flexibility)
it could be easily override (scalability)
plus, it’s easy to figure out

The use of !important to set a style “becoz’, otherwise, it duzn’t work and we dun’t know why” is a good indicator of a poor-quality CSS.

If you’re not a really good numbers person, here is an online CSS specificity calculator which can help you. The deal is to keep a specificity close to [0-0-1-0], which is equivalent to a class. Doing so, you won’t lose time anymore in debugging why your style doesn’t apply.

With Javascript

NB - Javascript is an abuse of terms. I mainly deal with JS libraries, jQuery as a reference.

It worth noting that vanilla JS will give better results and document.getElementById() is probably the most efficient.

A good ID

An identifier is the most efficient of selectors. Once the selector engine has found the element, it stops its journey through the DOM. The use of an identifier is relevant with Javascript because we want to deal with a precise, identified element most of the time.

In short, it’s much more efficient to isolate the identifier within the selector, then to chain with a query function to limit the scope for the engine:

$('#main-article .pagination**prev') // fast
$('#main-article').find('.pagination**prev') // 2 times faster

In the first attempt, the engine will search for all the elements from the DOM with the .pagination__prev class, then search for those who are inside the #main-article block.

In the second attempt, the engine will first search for the #main-article block, then for elements with the .pagination__prev class inside this block.

Please check performances by yourself.

Specific enough

This is a small bullet point worth noting. To increase the specificity at the right of the selector could increase the speed of the selector engine.

However, it’s pointless and counter-productive to make your selector far too heavy than necessary.

$('ol.nav--block .muted') // not-optimized
$('.nav--block li.pagination__next a.muted') // not-optimized
$('.nav--block a.muted') // optimized

Be careful with the universal selector

Updated on May 4th, 2013 after an insightful reading about the use of * in CSS and its performance impact (the performance paragraph).

Whether it is with CSS or JS, * could be the bugbear of selection performance.

Improperly used with CSS or, without knowing it, in JS selectors, this is the worst thing the selector engine could have to deal with, as it should check against all the DOM elements.

In CSS, ask yourself: do I really need to point out all the elements, whatever they are? “No” would probably be the answer.

This, is a bad idea:

.nav--block * {
  color: red;
}

When you read “within .nav--block elements, all the elements”, the selector engine read “all the elements, then those who have .nav--block as a parent”. From the right to the left!

However, this won’t lead to performance leak and shouldn’t be a concern excepted if you try to improve your Page Speed score beyond 90:

/* apply a natural box layout model to all elements */

* {
  -moz-box-sizing: border-box;
  -webkit-box-sizing: border-box;
  box-sizing: border-box;
}

In JS, if you don’t pay attention you’ll make it implicit by default. Plus, there should be alternative functions to achieve what you want to do.

$('.nav--block > *') // ouch!
$('.nav--block').children() // better

$('.form-fields :radio') // = $('.form-fields \*:radio');
$('.form-fields input:radio') // better

Last words

That’s it folks, that was my point of view over selectors.

These are best practices I learnt over time. It’s completely open to discuss, do not hesitate to do remarks, questions or suggestions below =)

Plop!

Lassés de Bootstrap ? Découvrez inuit.css !

Fri, 12 Apr 2013 00:00:00 GMT

inuit.css est-il fait pour vous ?

Pour faire simple, voici les cas de figure dans lesquels ce framework peut vous intéresser :

Vous avez besoin de mettre en place rapidement une architecture CSS décente
Vous découvrez/connaissez les avantages du code Orienté Objet et appréciez son adaptabilité et sa réusabilité
Vous devez implémenter un certain design qui ne colle pas forcément aux éléments “par défaut” des autres frameworks
Vous aimez le concept de framework mais, développeur dans l’âme, aimez avoir la main-mise sur le code

Et voici clairement le cas de figure où vous pouvez passer votre chemin (sauf si vous êtes curieux) :

Vous cherchez un framework CSS qui prenne en charge le design des éléments

En ce qui me concerne, je suis un assez grand utilisateur de Bootstrap. Mais en travaillant sur des projets où le design était imposé, je me suis confronté au problème de devoir surcharger le design du framework. Il faut alors annuler des effets par défaut, changer la couleur, la taille, … Ca fonctionne, mais vous vous retrouvez avec un CSS inutilement gonflé parce-que vous avez défini et redéfini les propriétés des mêmes éléments. C’est pas glop.

Ainsi, quand on veut produire un code CSS optimal et que l’on apprécie les valeurs de OOCSS on se rend compte que, dans certains cas de figure, Bootstrap n’est pas l’idéal.

Je suis donc tombé sur inuit.css, à peu près par hasard. Et comme je suis un peu curieux de nature, j’ai tenté le coup. J’ai adopté !

En guise d’overview, je ne peux que vous conseiller d’aller faire joujou sur les fiddles d’inuit.css !

Philosophie

inuit.css a été créé en Avril 2011 par Harry Roberts (c’est un anglais !).

Il est parti du principe qu’un framework CSS devait apporter une logique et un ligne de conduite pour le développeur, sans forcément le contraindre à un design particulier. Et comme le bougre n’est pas mauvais question bonnes pratiques CSS, il en a fait un framework.

inuit.css is a powerful, scalable, Sass-based, BEM, OOCSS framework.

inuit.css est développé en Sass. Sass est un pré-processeur CSS, une sorte de langage CSS amélioré permettant de réaliser pas mal de choses dont le CSS n’est pas capable (sélecteurs imbriqués, boucles, conditions, etc.). Le code du pré-processeur doit ensuite être compilé pour donner le fichier CSS final qui sera utilisé pour le site, car c’est bien le CSS qu’il faut fournir au navigateur, les fichiers Sass n’étant là que pour simplifier le développement.

inuit.css utilise la convention de nommage BEM. Alors pour le coup c’est un choix personnel du créateur qui peut être, comme toute bonne pratique CSS, controversée. C’est un coup à prendre, ça secoue les habitudes, c’est pas forcément très esthétique mais les avantages sont indéniables. Le mieux reste encore de lire l’article d’Harry Roberts sur la question car il l’explique très bien lui-même.

inuit.css est un framework OOCSS. C’est à dire que l’ensemble des composants du framework sont des objets indépendants, combinables et réutilisables. De plus, le framework tire partie des avantages de cette philosophie, ce qui le rend extensible à souhait sans crise de nerf à l’horizon. Je ferais un article sur les principes OOCSS, en attendant je peux vous conseiller les slides de Nicole Sullivan sur la question.

Installation

Pré-requis - avoir installé Sass au préalable pour pouvoir compiler le code.

A l’heure actuelle, inuit.css est passé à la version v5.0, ce qui change considérablement la manière de l’implémenter par rapport aux versions précédentes.

L’idée était d’en faire un module dont le coeur peut être mis à jour sans perturber le projet dans lequel il est implémenté. Toutes les configurations propres au projet ont donc été exportées en dehors du coeur, qui peut être mis à jour sans aucun problème.

Méthode 1 - Avec Git

Pour un nouveau projet, clonez simplement le dépôt de la manière suivante :

$ git clone --recursive git@github.com:csswizardry/inuit.css-web-template.git your-project-folder
$ cd your-project-folder
$ ./go

Le script go installe la dernière version de inuit.css.

Astuce - Si vous souhaitez incorporer le framework dans un projet existant :

$ git submodule add git://github.com/csswizardry/inuit.css.git your-project-folder/inuit.css

Il vous faudra ensuite organiser vos fichiers selon vos besoin, en vous inspirant de l’architecture du dossier css/ du template web.

Pour mettre à jour le coeur du framework, il suffira de mettre à jour le sous-module Git :

$ git submodule update

Méthode 2 - Sans Git

Téléchargez le template web puis téléchargez le coeur du framework et placez ce dernier dans le dossier css/ du template web. Placez le tout dans your-project-folder.

Pour mettre à jour le coeur du framework, il vous suffira de remplacer le dossier inuit.css par la version la plus récente.

Architecture et fonctionnement

Idéalement, créez également un dossier ui/ en parallèle de inuit.css/ pour y placer tout ce qui à trait au design de votre projet.

.
|-- inuit.css/         # Coeur du framework - ne pas toucher
|   |-- generic/       # Eléments standards (clearfix, reset)
|   |-- base/          # Eléments de base (tables, forms, …)
|   |-- objects/       # Eléments modulaires (grid, nav, …)
|   |-- _defaults.scss # Variables par défaut
|   |-- _inuit.scss    # Fichier principal du coeur
|
|-- ui/                # Dossier contenant vos fichiers Sass
|-- _vars.scss         # Variables configurables
|-- _style.scss        # Fichier principal de votre CSS
|-- watch              # Script pour compiler vos changements

Le dossier inuit.css/ contient le coeur du framework. Le truc, c’est de ne rien toucher à ce qui se trouve en dessous. De cette manière, le framework peut être mis à jour sans perturber les configurations de votre projet, ce qui n’était pas le cas dans les versions précédentes de inuit.css. Comme le framework n’impacte pas le design des éléments, le fait de considérer inuit.css/ comme un module que l’on peut mettre à jour est assez pertinent.

Le dossier ui/ contient idéalement vos fichiers de style à vous. C’est vous qui voyez pour le coup. Y’en a qu’ont essayé, ils ont pas eu de problème.

Le fichier _vars.scss doit contenir les variables du framework que vous souhaitez personnaliser. Vous avez la liste des variables par défaut dans inuit.css/_defaults.scss. Le process conseillé est donc le suivant :

recopiez la variable par défaut dans _vars.scss
changez $var: defaultvalue!default; par $var: newvalue;
rien d’autre

Vous avez également dans ce fichier l’ensemble des objets du frameworks contenus dans le dossier objects/. Vous pouvez les activer selon vos besoins, le framework est modulaire !

Le fichier _style.scss importe les fichiers Sass pour la compilation du CSS. C’est lui le grand architecte. A vous d’y incorporer les fichiers que vous aurez créé dans ui/ notamment.

Le script watch permet à Sass de compiler votre code à la volée lorsque vous faîtes des mises à jour. C’est pas impératif, ça dépend de votre workflow personnel… C’est vous qui voyez ! Le script est personnalisable et lance la commande suivante :

$ sass --watch style.scss:style.min.css --style compressed

Pour le lancer, inutile de mémoriser la commande précédente, exécutez simplement :

$ ./watch

En définitive, vous disposez d’un fichier CSS unique, compressé et optimisé, qu’il ne vous reste plus qu’à incorporer dans votre HTML :

<link rel="stylesheet" href="/your-css-folder/style.min.css">

Une version LESS ? Oui Môsieur !

Pour ceux qui, comme moi, utilisent LESS plutôt que Sass, il existe une version LESS de inuit.css entretenue par Peter Wilson et moi-même.

LESS est en effet une alternative plausible, même si moins puissante, à Sass. Ce pré-processeur est plus abordable dans un premier temps selon moi. Aussi, il fonctionne avec Javascript et non Ruby (les goûts et les couleurs me direz vous…).

Le seul hic est qu’il ne s’agit pas forcément de la même version. Si inuit.css est passé à la v5.0, l’alternative LESS correspond aujourd’hui à la v4.3.7.

Nous tâchons cependant de faire évoluer la version LESS avec l’optique d’offrir une version la plus up-to-date possible. Par exemple, Peter devrait traiter ma pull-request pour la v4.5 ce week-end et j’ai actuellement la v4.5.4 dans les bacs donc c’est une question de temps !

Edit du 15/04 - La version correspond à présent à la v4.5 et la v5.0.0 est en chemin !

Edit du 23/05 - La version actuelle correspond à la v5.0.0 qui comporte le template web ainsi donc que le coeur du framework (même principe, mais en LESS).

Pour ceux qui auraient des questions diverses et variées sur le framework, n’hésitez pas à laisser des commentaires ci-dessous.

Et si vous êtes curieux et avides de découvrir ce qu’est le CSS qui déchire, give it a try !

Tired of Bootstrap? Discover inuit.css!

Fri, 12 Apr 2013 00:00:00 GMT

Is inuit.css built for you?

To make it easy, you could find this framework interesting in theses cases:

You need to quickly setup a decent CSS architecture
You discover/know about Object Oriented advantages and like its scalability and reusability
You should implement a specific design which doesn’t fit well with the “default” elements of others frameworks
You like the framework concept but, as a developer, you like to get your hand dirty into code

However, this framework may not be a good choice for you in such a situation:

You are searching for a CSS framework which takes care of elements design

Personally, I used a lot Bootstrap. But, working on projects where design has been imposed, I faced the issue of being overriding the default design of the framework. You should most of the time cancel defaults effects, change color, size, … It works, but you are bloating your CSS with useless code because you defined and redefined the same properties of same elements. It could have been better.

Thus, when you want to produce an optimal CSS and you appreciate OOCSS values, you realized that, under some circumstances, Bootstrap is not always the ideal solution.

I finally found by chance inuit.css. As I’m a curious guy, I gave it a try. I love it!

As an overview, I’d suggest you to play around with inuit.css fiddles!

Philosophy

inuit.css was created in April 2011 by Harry Roberts.

This guy made the assumption that a CSS framework should bring some kind of logic and guideline to the developer, without impose any specific design. As this dude isn’t that bad in term of CSS best practices, he made them a framework.

inuit.css is a powerful, scalable, Sass-based, BEM, OOCSS framework.

inuit.css is developed in Sass. Sass is a CSS preprocessor, some kind of improved CSS language which allows you to do a bunch of nice stuff that vanilla CSS can’t do (nested selectors, loops, conditions, etc.). The preprocessor code should be compiled to produce the final CSS file which would be used for the browser. Sass files just make the development a piece of cake.

inuit.css use the BEM naming convention. This is a very opiniated choice of its creator which can ba, as every best practice, questionable (or at least debated). It can hurts your feelings, mostly because it looks ugly the very first time you see it, but it’s really worthy. I’d suggest you to read Harry Roberts’ post about that as he explained it very well.

inuit.css is an OOCSS framework. I mean that every component of the framework is an independent, combinable and reusable object. Futhermore, the framework takes advantages from that philosophy which means that you can extend it without any hassle. I’ll probably write a post about OOCSS principles. Until then I can suggest you to have a look at Nicole Sullivan’s slides on this topic.

Installation

Pre-requisite - have Sass installed in order to compile the code.

At present, inuit.css has reached v5.0, which considerably change the way you implement it regarding older versions.

The idea was to make it a module so you can update the core without disturb the project in which it’s implemented. All project specific configurations have been exported outside of the core, so you have no trouble in upgrading this one.

Method 1 - With Git

For a new project, just clone the repo as follow:

$ git clone --recursive git@github.com:csswizardry/inuit.css-web-template.git your-project-folder
$ cd your-project-folder
$ ./go

The go script install the las version of inuit.css.

Tip - If you want to install the framework in an existing project:

$ git submodule add git://github.com/csswizardry/inuit.css.git your-project-folder/inuit.css

Then you’ll need to organize your architecture regarding your needs, with the inpiration of the css/ folder from the web template.

In order to update the framework core, you just need to update the git submodule:

$ git submodule update

Method 2 - Without Git

Downloas the web template and then the framework core. Place the core under the css/ folder of the web template. Then copy all of these in your-project-folder.

In order to update the framework core, you just need to replace the inuit.css folder with the most recent version.

Architecture and working

Ideally, create a ui/ folder beside the inuit.css/ one to put every file which deals with the design of your project.

.
|-- inuit.css/         # Framework core - do not touch
|   |-- generic/       # Standards elements (clearfix, reset)
|   |-- base/          # Base elements (tables, forms, …)
|   |-- objects/       # Modular elements (grid, nav, …)
|   |-- _defaults.scss # Defaults variables
|   |-- _inuit.scss    # Main setup file of the core
|
|-- ui/                # Folder containing your Sass files
|-- _vars.scss         # Project specific variables
|-- _style.scss        # Main setup file of your project
|-- watch              # Script which watch for changes

The inuit.css/ folder contains the framework core. The trick is not to touche anything under. Doing so, the framework can be updated without hassle nor risk for specific configuration override, which was not the cas in previous versions of inuit.css. As the framework doesn’t impact the design of elements, considering inuit.css/ as a module you can update sounds relevant.

The ui/ folder ideally contains your own style files. It’s up to you: your rules, your code of conduct.

The _vars.scss file should only contain the framework variables you’d like to override. You can find the list of existing variables in inuit.css/_defaults.scss. The suggested process is the following:

copy the default variable in _vars.scss
change $var: defaultvalue!default; for $var: newvalue;
that’s it

You’ll also find in this file that you can activate or deactivate any of the objects/ components of the framework, regarding your needs.

The _style.scss file imports Sass files for the CSS compilation. It’s the great architect. It’s up to you to add files you’ll eventually create under ui/.

The watch script allows Sass to watch for changes in order to do the compilation automatically. It’s not necessary, it depends on your personal workflow… It’s up to you (always)! You can customize it. It basically launch the following command:

$ sass --watch style.scss:style.min.css --style compressed

But wait, you don’t have to remember this! Just execute the file and you’re done:

$ ./watch

At the end, you’ll have a unique, compressed and optimized CSS file you just need to load from your HTML:

<link rel="stylesheet" href="/your-css-folder/style.min.css">

LESS version? Yes sir!

For those who, just like me, use LESS instead of Sass: a LESS port for inuit.css exists and is maintained by Peter Wilson and myself.

Indeed, LESS is a relevant alternative to Sass, even though Sass is more powerful. This preprocessor is easier to adopt at a first sight, IMHO. Futhermore, it works with Javascript, not Ruby.

The only problem is that it’s not necessarily up-to-date as inuit.css is already v5.0 and the LESS port still correspond to the v4.3.7.

Edit 4/15 - Version is now up-to-date with v4.5 and v5.0.0 is coming!

Edit 5/23 - The current version is now v5.0.0 coming with the web template and framework core (same principle, in LESS).

For those who’d eventually have some questions about the framework, don’t hesitate to put comments below.

If you’re curious and want to discover what is fuckingood CSS, give it a try!

S'amuser avec les interactive playground

Wed, 10 Apr 2013 00:00:00 GMT

Interactive playquoi ?

Il s’agit en fait d’un IDE en ligne permettant de réaliser du développement front-end (HTML, CSS et JS bien souvent) et de visualiser le résultat.

La plupart permettent également de sauvegarder le code et de le partager, ce qui mène à un certain nombre d’applications pratiques de ces outils à savoir :

débogage de codes, l’environnement permettant de reproduire un bug ou un effet non désiré et d’en isoler la cause, ce qui en fait un outil particulièrement apprécié des développeurs.
création de snippets, particulièrement utile pour répondre à une problème ou une question sur StackOverflow (par exemple) ou pour réaliser des showcases.
enseignement par mise en pratique utilisé par des sites tels que CodeSchool, produisant de véritables TP-live pour mettre en pratique ce qui vient d’être vu.

Voici donc, après cette petite mise en jambes, une petite présentation non-exhaustive des web playgrounds que je connais et que j’affectionne.

JSBin

JSBin est le premier que je connaisse. Un vieux de la vieille qui existe depuis 2008. Il dispose des 4 panels classiques pour éditer le HTML, le CSS, le Javascript et constater le résultat. Il dispose également d’un panel Console qui tient le rôle de console javascript une fois le code interprété. Fait appréciable : les modifications apportées au code sont visibles en temps réel.

Particulièrement abouti, il permet d’interpréter directement les Gist, ce qui est appréciable en soi pour les grands adeptes de la plateforme.

Gist est un moyen rapide et efficace que propose Github pour partager des snippets de codes versionnés sous Git. JSBin permet donc de visualiser directement dans le navigateur le rendu du code, permettant de le modifier et de sauvegarder une nouvelle version du Gist.

Il dispose également d’un certain nombre de features notables comme JSHint (un linter qui vérifie que votre Javascript ne comporte pas d’erreur) ou encore la possibilité d’insérer le JS/CSS à un endroit spécifique du HTML avec %code%/%css.

Points forts

Pas nécessaire d’être enregistré pour l’utiliser
Visualisation du rendu en temps réel
Intégration de Gists
Particulièrement riche en fonctionnalités (JSHint, Ajax, templates, ZenCoding, …)
Les JSBin peuvent être intégrés et modifiés directement dans des sites web

jsFiddle

jsFiddle fonctionne peu ou prou selon le même principe, avec une interface à l’ergonomie quelque peu différente.

Les fonctionnalités sont sensiblement les mêmes à ceci près que jsFiddle permet toutefois de coder en SASS plutôt qu’en CSS et en CoffeeScript plutôt qu’en Javascript, ce qui peut être un argument pour les aficionados de ces pré-processeurs.

Fait notable également : le HTML est épuré, il est inutile de renseigner les entêtes ou le doctype puisque le code du panel sera de facto intégré entre les balises <body>. En contrepartie, la configuration du doctype et des informations se fait sur le côté, via un panneau de configuration.

Harry Roberts utilise d’ailleurs jsFiddle pour présenter les fonctionnalités d’inuit.css, ce qui permet de se faire rapidement une idée de comment fonctionne le framework et de ses capacités sans même avoir à le télécharger.

Points forts

Pas nécessaire d’être enregistré pour l’utiliser
Intégration de Gists
Particulièrement riche en fonctionnalités (TidyUp, JSHint, Ajax, ZenCoding, …)
Possibilités d’utiliser des pré-processeurs CSS/JS
Les fiddles peuvent être intégrés directement dans des sites web, mais pas modifiés

CodePen

Codepen est une autre version assez populaire, avec un style quelque peu différent et une stratégie économique établie. En effet, CodePen propose une version PRO permettant par exemple de dispenser un cours en temps réel, ou bien de coder à plusieurs collaborateurs, simultanément, en live.

CodePen propose un certain nombre de features intéressantes, y compris l’usage de pré-processeurs. A noter qu’en se connectant avec son compte Github, les Pens que l’on crée se transforment automatiquement en Gists sur notre compte. Les modifications se font également en temps réel…

En revanche il faut être connecté afin de pouvoir intégrer les Pens, ce qui ne nécessite pas forcément de créer un compte si l’on dispose d’un compte Github. De nombreuses fonctionnalités de CodePen vont également bien plus loin que les précédents projets mais sont réservées à la version PRO (business is business, ce qui est tout à fait compréhensible en soi).

Points forts

Pas nécessaire d’être enregistré pour l’utiliser
Visualisation du rendu en temps réel
Sauvegarde des Pens en tant que Gists
Particulièrement riche en fonctionnalités (JSHint, Ajax, ZenCoding, …), notamment avec un compte PRO
Possibilités d’utiliser des pré-processeurs CSS/JS/HTML
Les Pens peuvent être intégrés directement dans des sites web, mais pas modifiés

dabblet

dabblet est un peu particulier dans le genre. En effet, ce dernier s’oriente non pas sur le Javascript (fer de lance de JSBin et jsFiddle, rien que par le nom) mais sur le CSS.

L’idée de Léa Verou était de produire une alternative qui ne s’embarassait pas de requêtes HTTP à chaque fois que l’on fait/code quelque chose dans l’éditeur. Si cela prend sens pour le Javascript, ce n’est d’aucun intérêt quand on ne cherche qu’à tester du HTML/CSS.

Sous son apparence design, dabblet offre également tout un panel de fonctionnalités comme la visualisation du rendu en temps réel, des “inline previewers” particulièrement sympathiques sur toutes sortes de propriétés CSS (pour visualiser une longueur, une couleur, un effet, …) et même l’incorporation native de -prefix-free, luxe ultime pour tout développeur CSS. Ce dernier vous permet d’utiliser les propriétés CSS3 sans vous préoccuper des préfixes, il les ajoute en background quand c’est nécessaire.

A noter cependant que, sous la demande, dabblet expérimente également la possibilité d’intégrer du Javascript. Mais il y a fort à parier que ce sera juste un possibilité offerte et non pas le fer de lance de cet environnement, bien au contraire !

Points forts

Pas nécessaire d’être enregistré pour l’utiliser
Visualisation du rendu en temps réel
Synchronisation totale avec les Gists (connecté sous Github)
Inline previewers et utilisation native de -prefix-free pour le développement CSS
Les dabblet peuvent être intégrés et modifiés directement dans des sites web

Le problème, c’est le choix

Il y a effectivement de quoi faire et suffisamment d’environnements pour que chacun s’y retrouve. Chaque développeur peut s’orienter vers la solution qui s’adapte le plus à ses besoins, qui lui convient le mieux, qui le séduit le plus. Et tout comme pour les IDE, rien n’interdit de passer d’un environnement à un autre, pour se faire une idée, au contraire.

Personnellement, j’utilise beaucoup jsFiddle jusqu’à présent…
… je garde un oeil sur JSBin mais je n’ai pas eu de grosse raison de changer d’environnement pour le moment…
… CodePen ne me convient pas exactement, même si je le trouve cool dans l’esprit…
… et dabblet est mon petit coup de coeur que j’ai découvert récemment. Il n’est pas encore aussi mature que les autres, mais il a des atouts indéniables qui justifient le détour.

Play around with interactive playgrounds

Wed, 10 Apr 2013 00:00:00 GMT

What are we talking about?

An interactive playground is basically an online IDE which allows you to do some front-end development (HTML, CSS and JS most of the time) and visualize the result.

You can also save and share your code with most of them, which leads to a bunch of practical uses:

code debug, as the environment allows you to reproduce a bug or non-desired effect and to isolate the root cause. That’s why such tools are specially appreciated by developers.
snippets creation, which is very useful to answer a problem or question on StackOverflow for instance. You can also easily create showcases.
teaching concretely, which is used by websites such CodeSchool as they developed powerful live challenges to put into practice what you just learned.

This was a nice way to get into the swing. Now let me present you a non-exhaustive overview of web playground I know and like so far.

JSBin

JSBin may be one of the very first which became popular. It exists since 2008. It has the classic 4 panels to edit HTML, CSS, Javascript and the output. It also disposes of a Console panel which stands for a Javascript console after the code being interpreted. Significantly, modifications you made are instantly visible on the output.

Very elaborated, it can interpret Gist directly which is particularly nice for those who use it.

Gist is a quick and efficient way that Github proposes to share git versionned code snippets. JSBin can show you directly in your browser the code output so you can modify and save a new version of the Gist.

It finally has a bunch of nice features such as JSHint (a Javascript linter) or the possibility to input the JS/CSS code at a particular place in the HTML with %code% and %css.

Strengths

No need to sign in to use it
Real-time visualisation
Gists integration
A lot of functionalities (JSHint, Ajax, templates, ZenCoding, …)
Dabblets can be integrated directly into websites, and modified from there

jsFiddle

jsFiddle works more or less with the same principles, witha bit different UI.

Features are mostfully the same but jsFiddle allows you also to code in SASS instead of CSS, and CoffeeScript instead of Javascript. That could be an argument for preprocessors aficionados.

Bonus point: HTML is reduced to the strict minimum, there is no need to specify the <head> part, nor the doctype. Your code will directly be injected into the <body>. You can still configure all of this on the different sections of the sidebar.

Harry Roberts currently uses jsFiddle as a showcase of inuit.css features, so you can have a quick overview of the framework capacities before you decide to download it.

Strengths

No need to sign in to use it
Gists integration
A lot of functionalities (TidyUp, JSHint, Ajax, ZenCoding, …)
Possibility to use CSS/JS preprocessors
Fiddles can be integrated directly into websites, but not modified from there

CodePen

Codepen is another popular example of interactive playgrounds. It comes with a different styling approach and a well-established business model. Indeed, CodePen has a PRO version which allows you for instance to give a real-time class or to code all together with collegues, simultaneously, in live.

CodePen offers a bunch of interesting features, preprocessors use including. You should note that if you login with your Github account, your Pens will automatically be converted as Gists in your account. And, by the way, did I say that modification are visible in real-time?

On the flip side, you must be connected if you want to integrate Pens into websites, which doesn’t mean you have to create a CodePen account if you already have a Github one. A lot of CodePen features go far further projects I mentioned before, but they are PRO-features (business is business, which is really understandable here).

Strengths

No need to sign in to use it
Real-time visualisation
Save Pens as Gists
A lot of functionalities (JSHint, Ajax, ZenCoding, …) and more with a PRO account
Possibility to use CSS/JS/HTML preprocessors
Pens can be integrated directly into websites, but not modified from there

dabblet

dabblet is a bit different of its kind. Indeed, this one is CSS focused and not Javascript (you already have JSBin and jsFiddle for that dudes).

Léa Verou’s idea was to give an alternative which doesn’t bother with HTTP request each time you do/code something in the editor. If that makes sense for Javascript, there is no need for these request when you just want to play arount with HTML/CSS.

Under his nicely designed UI, dabblet also offers a bunch of features such as real-time visualisation, inline previewers which are definitely useful to visualize CSS properties (lengths, colors, effects, …) and the native use of -prefix-free, the ultimate luxury for any CSS developer. You can use CSS3 properties without thinking about prefixes issues as it deals with it when necessary.

You might note that, under requests pressure, dabblet is experimenting the possibility to integrate Javascript. But there are good reasons to bet that it will just be an add-on and not the cutting edge of the platform.

Strengths

No need to sign in to use it
Real-time visualisation
Total synchronisation with Gists
Inline previewers and massive use of -prefix-free for CSS development
Dabblets can be integrated directly into websites, and modified from there

The problem is choice

There’s tons to give enough environments to please anyone. Each developer can choose the solution which fits the most its needs, the one he likes and seduced him the most. Just like IDE, you can give each of them a try and decide by yourself which tool is the best for you.

I personnaly used jsFiddle a lot until then…
… I keep an eye on JSBin, but I never felt the need to change for it yet…
… CodePen doesn’t fit my needs, even though I find it cool…
… and dabblet is my coup de coeur I recently discovered. It’s not as mature as the others but already has remarkables assets which justify the try.

Faire son blog avec Jekyll

Sun, 07 Apr 2013 00:00:00 GMT

Kesako Jekyll ?

Jekyll est un générateur de sites statiques, pensé pour les blogs, développé en Ruby, simple à utiliser. Basiquement, une fois que vous avez construit vos templates .html, il ne vous reste qu’à rédiger vos articles sous le format qui vous sied le mieux (le Markdown me convient tout à fait) et basta, le serveur fait le reste !

C’est Tom Preston Werner, le co-fondateur de Github, qui l’a créé.

D’ailleurs (et surtout), c’est ce qu’utilise Github Pages pour générer vos pages. Basiquement, il suffit de pusher le code sur Github pour l’avoir en ligne (c’est magico-magique).

Le principe de fonctionnement est assez simple, l’architecture rapide à prendre en main. C’est vraiment pensé pour que vous vous concentriez sur le contenu plutôt que le contenant (tout en laissant le plaisir de créer ses templates de A à Z, bien que Github propose également de faire ça à votre place).

Jekyll plutôt que Wordpress

Quand j’ai finalement voulu créer mon blog, plusieurs options sont venues à moi. Les plus valides étant un site Wordpress (ce CMS vaut vraiment le détour) ou bien en passant par Jekyll.

Bien que le second ne soit pas aussi populaire que le premier, c’est vers cette solution que je me suis tourné pour les raisons suivantes :

Je n’ai pas besoin de base de données et je ne voulais pas m’encombrer avec de la mise en place (ou de la maintenance) de BDD. Sérieusement, j’ai juste besoin de front-end. C’est du contenu statique, rien d’autre. Pas de brèche de sécurité back-end. Ma seule dépendance c’est mon hébergeur : Github (et encore, ce n’est qu’un dépôt Git comme un autre).
Je veux que mon blog se mette à jour dès que je push sur Github. J’aurais évidemment pu faire un hook pour déployer cela ailleurs, mais cette solution me libère de cette contrainte.
Je n’ai besoin de rien à part ce que Jekyll propose. Il est pensé pour les blogs. Il y a des templates, de la pagination, un peu de logique si besoin, de la configuration et c’est tout.
J’aime suivre les nouvelles tendances et Jekyll fait partie de ces projets innovants et solides qui voient le jour au rythme de l’évolution du web.

Bien entendu il y a beaucoup du fait que, étant développeur, je n’avais pas envie d’utiliser un CMS prêt-à-porter pour mon propre blog.

Wordpress est un excellent CMS (que je recommande chaudement) qui est facile à prendre en main, dispose d’une excellente communauté française et qui convient tout à fait à tout blog ou autre site vitrine pour quiconque ne souhaite pas s’embêter avec du code.

Mais en ce qui me concerne, je veux être au coeur du code. Je veux développer dans mon IDE. Mais je veux que ce soit simple. Que ça aille droit au but. C’est ce que fait Jekyll.

Mise en place et configuration

La prise en main de Jekyll n’est pas très complexe, mais vous ne trouverez pas beaucoup de ressources en français (hé, what did you expect?). Voici les étapes telles qu’elles sont décrites :

Installez le gem (oui, c’est du Ruby).
Jetez un coup d’oeil au fonctionnement et à la configuration
Créez la structure de base de votre site (vos templates).
Créez vos posts (ou importez-les depuis votre précédente plateforme)
Lancez votre site en local pour voir le rendu
Déployez le tout

Structure de Jekyll

.
|-- _includes/      # Bouts de codes à inclure ailleurs
|-- _layouts/       # Vos templates
|   |-- default.html
|   |-- post.html
|-- _plugins/       # Plugins (optionnel)
|-- _posts/         # Vos posts
|   |-- 2013-04-07-faire-son-blog-avec-jekyll.md
|
|-- index.html      # Fichiers html
|-- about.html
|-- (…)
|-- _config.yml     # Fichier de configuration

Jekyll compile l’ensemble dans un dossier _site/ contenant votre site statique final.

$ jekyll —server dans un terminal lancera le serveur. L’URL par défaut est donc http://localhost:4000/, ce qui peut être modifié dans la configuration.

$ jekyll —no-server —no-auto compilera simplement le code source sans lancer le serveur (ça peut servir, dans le cadre d’un script de déploiement par exemple).

Créer un post

Basiquement, le code source de mes posts se présente ainsi :

---
layout: post
robots: index,follow
published: true

tags: [jekyll]

title: Faire son blog avec Jekyll
description: Pourquoi et comment créer son blog avec Jekyll plutôt qu'un bon vieux Wordpress des familles.
---

## Kesako Jekyll ?

[Jekyll](https://github.com/mojombo/jekyll) est un générateur de sites statiques, pensé pour les blogs, développé en _Ruby_, simple à utiliser.

Cette entête YAML permet de configurer mes posts de manière à ce que Jekyll les interprète intelligemment. Ainsi je définis notamment le layout, l’état de publication de l’article, son titre et sa description… Jekyll fait le reste. La suite, c’est du Markdown.

L’hébergement

En ce qui me concerne, j’ai choisi d’héberger mon site directement sur Github. Github Pages permet d’héberger son site statique gratuitement et facilement.

Il suffit de créer un dépôt username.github.io (dans mon cas nicoespeon.github.io). Le contenu de la branche master est utilisé pour le site statique. Le site est disponible par l’URL http://username.github.io.

Il est également possible d’acheter un nom de domaine (sur OVH ou Gandhi par exemple) et de faire une redirection DNS :

Créez un fichier CNAME à la racine du projet, contenant votre nom de domaine (nicoespeon.com par exemple)
Faîtes pointer A vers l’IP de Github 204.232.175.78 (dans les Zones DNS chez OVH).
Attendez quelques heures le temps que ça se synchronise
Dégustez tant que c’est chaud

Le mot de la fin

C’est tout pour cette petite introduction à l’utilisation de Jekyll. Si l’anglais ne vous rebutte pas, vous trouverez votre bonheur sur Google. Je vous suggère notamment cet article de Harry Roberts et celui-ci de Hugo Giraudel (c’est un français !) qui m’ont inspiré et conforté dans mon choix.

Building a multilanguage Jekyll blog

Sun, 07 Apr 2013 00:00:00 GMT

Note on compatibility

What follows consider the use of Jekyll v0.12.1.

Looking for Jekyll v1.5? Go have a look to the one of April 2014.

Please note that some major changes happened in Jekyll v1.0.0 which made some of the following tricks not working anymore (I’m thinking about plugins). I’ll write a new post when upgrade my own Jekyll to v1.0+.

If you wish, you can still install the old Jekyll version with the following command:

# Install the old version of jekyll
$ sudo gem install jekyll --version 0.12.1

# Uninstall your current version if you dowloaded it
$ sudo gem uninstall jekyll --version <your current version>

Why Jekyll?

I won’t write a n-th post about the reason of choosing Jekyll as the static site generator for my blog. There are already plenty of them.

I’ll just sum it up with the following bullet-points :

I don’t need to deal with a database. I just want to Keep It Simple (Stupid) and front-end will just do it well.
I want to have my website updated when I push it to Github. I could have done some hook to deal with that but I don’t have to, thanks to Github Pages.
I love keeping myself up-to-date with new trends. And the Jekyll approach just sounds good to me.

I could recommend you the post from Harry Roberts and the one from Hugo Giraudel which comforted me in my choice.

What about multilingual?

The thing is, Jekyll is not actually build to support multinlingual blogs. The Liquid date filter will display the english version of the date. Futhermore, if you want to distinguish posts by their language, then you have to create a category per language. But the Jekyll .paginator is not build to deal with categories, which is kind of a problem.

Nevertheless, I wanted to create my blog both in French and English for few reasons :

Most of the nicest websites treating about front-end development are in English, which is fine but I would like to see few of them written in my native language for other French developers who may not be fluent in English (even if they should be).
I’m French and proud to be. Although I love English, there’s no reason for me not to write some posts in my native language too.
This is a challenge and I love challenges… as every developer does, right?

So here’s the strategy:

English is the default language, at the root level.
Each language represents a category, which could be done thanks to the folders architecture.
The French part should be under the /fr base url, which is fine with the previous statements.
English posts should only display into /index.html, - French posts should only display into /fr/index.html (and the pagination should be done accordingly).
It should Keep It Simple (Stupid).

Let’s build the architecture for the source files:

.
|-- _includes/      # Partials included in other files
|-- _layouts/       # Templates of the website
|-- _plugins/       # Plugins to override Jekyll workflow
|-- assets/         # LESS/CSS, JS, images, …
|-- fr/             # French category
|   |-- _posts/     # French posts
|   |-- index.html  # French html files
|   |-- about.html
|   |-- (…)
|
|-- en/             # English category
|   |-- _posts/     # English posts
|
|-- index.html      # Default html files (EN)
|-- about.html
|-- (…)
|-- _config.yml     # Jekyll configuration file

When launched, Jekyll generates the static final website into the _site/ folder.

I use the _config.yml file to put some locale variables I could use in the main templates.

This is definitely not the cleanest solution in my humble opinion, but it’s quite easy to deal with and it works fine for the moment. It may change in the future in a smarter way to handle this.

Plugins on the road

In order to solve the mentioned problems, I used 2 plugins to override the regular Jekyll workflow.

1. Pagination per category

category_pagination.rb has the paginator only considers posts of the current category in order to distinguish the two languages.

I modified the original plugin to have the default category, at root level, set as the English one instead of displaying all of the site.posts.

2. i18n Filter

i18n_filter.rb customizes the page.date treatment accordingly to the locale.

I’ve had to add the _locales/fr.yml file to create the localize function. It performs just as the date does, but it displays the French format for the date.

The Github thing

Plugins are set up, templates are built, design has been completed, the git workflow is ready and so is the remote repository on Github. Let’s push!

The DNS redirection for my custom domain just works fine but… wait. It doesn’t play as expected. Damn it! I just notice that Github is running Jekyll in --safe mode, which means that plugins are disabled. And so are my category pagination and my i18n filter.

For every problem, a solution, with Google being your best friend. I found inspiration to redesign my personal workflow in that way.

Let’s have a look to my branching model.

The master branch correspond to the compiled website (the one generated into _site/ directory) so that Github can deliver it directly as a static website, thanks to the .nojekyll file. The develop branch correspond to the source files, as I would like to keep them tracked and open-sourced. They would be compiled with Jekyll in order to proceed to deployment. There’s no more merge from develop into master as there’s only deployments from now. I just work on develop and, when I’m ready, I deploy the whole site with a new commit on master.

Of course I already pushed the first commits when I realized I was wrong. But instead of recreating the whole repo and rebase my git history, I decided to deal with it with just few commits to correct the situation. There’s no shame in doing mistakes after all.

I just created a Makefile in order to do all that stuff with a make deploy command. And voilà!

And here we go

Here we are, it just works perfectly and I’m now ready to go with a both English and French, Jekyll-flavored, Github-hosted blog \o/

There is still enhancements I should take care of -such as deploying a Google Analytics and a comments system- but I’m satisfied with the result. The challenge is taken up and the journey has begun. Let’s transform these posts into a monster.