Git good practices

Here are a few git tips that I find essential :

1. Use git on all your projects, even your personal projects

When you work on a project on your own, you might think you won’t need git because you don’t need to share your code. However, git is not just a way to share your code but rather to retain history. So that means that by using git, you are going to be able to look up older versions of your code. For example, if you find a bug that you didn’t have before, you can use git bisect to find out which commit introduced the bug. This makes debugging much easier. You will also be able to develop many features separately, and merge them back into your master branch whenever they are finished. Most importantly, if you do changes that you think will lead to nowhere, you can reset your code to the latest commit with git reset HEAD --hard, or you could also save those changes for the future by creating a stash with git stash save "stash message" . If you don’t have good memory, you will also be able to see if and when you developed a new feature.

2. Rewrite your history, because a clean history makes things simpler

I very often do interactive rebases, with the git command git rebase -i <commit-id>. It gives you the possibility to change the commits after . Be careful not to change published history. What I use most of the time:

  • fixup can meld two commits into one,
  • reword lets you change the commit message of a commit, when you made a typo in your commit message, or just want to add a summary to that commit message.

With clean history, you will be able to understand the project history much better : what features where developed, by whom, and what parts of the code were changed to achieve that new feature. Lots of people are impressed to see that I don’t need to ask someone how he added a specific feature, the secret is just to look at project history.

3. Have strict convention for your commit messages

I personally like to have my commits written in english, in active present form, eg:

BAD: added XYZ feature GOOD: Add XYZ feature

Also, I recommend to follow advice from tpope’s blog post about commit messages.

4. Don’t use git commit -m « message »

I think it is bad practice to use the -m option of git commit, because it doesn’t enforce you to take time to think about your commit message. It’s also a few letters less to press to start (no ‘-m «  »‘). Just start using your editor to write those commit messages, you will see that the quality of those messages will increase significantly.

5. Don’t add unrelated stuff to a commit message

If you find a typo somewhere whenever you’re coding a new feature and want to commit it, don’t put it in the same commit than your feature. The problem if you do so is that it is no more possible to tell when you fixed the typo from the commit messages. Also if you git revert that commit because you want to remove that feature, you will also revert the correction of the typo fix, which you might not even see.

6. Use git add –patch or git add –interactive

When using git add file, or even git add . , you lose a lot of control about what you put inside your commit and what you don’t. By using git add <file> --patch, you will be able to select which lines you would like to put into your staging area and which line you want to keep out of it.

7. It’s ok to work however you want, as long as the published history is clear

I personnaly use tig, which is a text-based interface for git that runs inside the command line. They are many GUIS that can manage your git repository, for example SourceTree. Be aware that knowing the command line api of git is very useful for all advanced tasks. Also, it will work even if you don’t have a display (such as when you ssh).

Riot overview : the new React like JS micro-Framework

Over the weekend, I tried to play around with Riot. Riot is very sharply focused on doing one thing right. The library is very small: 3.5kb minified. One file is responsible for one UI element, for example a todolist. That file contains both the HTML and JS responsible for that component. A UI element is represented in your application with a custom tag, for example « . You’re responsible for loading data for that view, and anything else that is not directly bound to the User interface. In that way you could very easily replace only the Storing engine for one particular UI element for example.

The syntax is very easy to learn and still very expressive. For example to have a checked attribute set when one of your variable is truthy, you could write the following code:

to have a checkbox that is checked by default.

The JS you use inside your templates can be written in ES6, the code will automatically be transpiled into working ES5 JS.

So for example, you could write:

You also have support for loops, transclusion, including scoped CSS (that will only be used in your custom tags).

The design guide is to use an event based architecture: You should load data, and have your business logic separated from your UI, and communicate changes from the Store to the UI. The UI will then call events to a global Dispatcher (which can be done with the 10 lines library RiotControl), The Dispatcher then dispatches events to the stores, that may send event to the UI as a result. With this, you have implemented a Flux architecture .

The Documentation of Riot 2.0 is very well written, easy to grasp and completely uptodate.

Riot is a UI-framework you should definitively take into consideration

How to run io.js in Travis CI

UPDATE: Travis CI now supports io.js

It’s now much easier to use iojs on travis: Just write the following:

Base Article

Here’s just a small code snippet to show how you can run your tests with io.js in Travis CI.

At the current time, Travis CI doesn’t support io.js like it does with other options. So you will have to use the before_script argument in your travis.yml

Here’s how the .travis.yml looks like

of course, you could also do this for mocha, and any other cli tool.

Hope this helps

Interviewers: stop the puzzle games !

I was active in looking for a job in a software company in the past three months (although I also did some contract work), and I failed at a puzzle game test because « I was too slow to answer the questions ».

Here are a some of the questions I was asked to do:

You are given a string variable $str.
Write PHP code to print the given string with every third letter removed.
For example, if input string is « Apple iPhone », the output should be « ApleiPon ».

 

Array $a contains integer numbers. Write PHP code to print an index of an element that contains the maximum value among array values that are even numbers (can be divided evenly by 2).

 

The questions and quizzes I’m going to talk about are the ‘basic’ quizzes, where your task is very near to algorithmic: eg write a function that sorts an array,
write a function that finds an integer inside an array, etc

tl;dr

They are many reasons for which I think this kind of questions do not make sense to choose between candidates.

  1. Some people will cheat
  2. It doesn’t show how you organize your code
  3. It doesn’t show how you work with others

Some people will cheat

In the book « The honest truth about dishonesty » by Dan Ariely, he explains that the most effect of cheating doesn’t come from big cheaters but rather from many cheaters.
In other words, they are not a few people who are tempted to put lots of effort to cheat.
However, they are many people who would put some effort to increase their score artificialy.
For example that could be done by using one or many of the following tricks (ordered from the difficult to the easiest):

  • If the test doesn’t require you to login, you could do the test twice, the first time providing information false information. This way, you can prepare
    yourself to the questions that are asked and achieve a score that is higher than what you could do normally
  • If you have unlimited time for the test (eg have one week to complete it), than you could very easily ask the help of a friend or even ask you question on
    a forum to make you smarter.

It doesn’t show how you organize your code

One of the biggest problem with quiz like problems is that you don’t encounter them in real life. You already have functions that can sort arrays in most of the
languages, or you could easily find a library that takes care of this for you.

The real difficulty in a codebase is not how to sort an array, or if that is the case your programmers are probably not that good. The real difficulty in a
codebase is how to organize your code.

I would also like to talk about a very positive experience when looking for a job : it was the test of the Financial Times Lab. They ask you a set of questions
which are « Stackoverflows » style of question, eg they ask you what’s the difference between

helloWorld()
function helloWorld() {
console.log(1);
}

and

helloWorld()
var helloWorld=function () {
console.log(1);
}

and why they give different results.

It doesn’t show how you work with others

Working with others is a huge part of what a programmer does. To achieve a task, some work must be done. But what takes most effort is the communication between
members of the team. If the communication doesn’t work well, your project isn’t going to meet it’s deadline.

Work in progress

Your support tickets are just the tip of the iceberg

Iceberg
The tip of the iceberg

If you run a product and have some kind of support system, you’re for sure, depending on the number of customers, managing a few support tickets per month. You might think « why are my users so stupid ? » , but this is not even the tip of the iceberg. Think about it from the user perspective. How many times are you annoyed by something a day ? Probably somewhere between five and ten times a day. And how often do you take the time to share your problem to the app’s creator? Probably once a day of you’re quite a world improver.

They are so many broken things that most of what is broken will not reach to you because other things are much more annoying.

By removing the most painful problems first, you will be able to get some feedback from the less urgent things.

Vim serving as a model for keyboard-based software

vim is a good example (if not the best) of a keyboard based application. Vim being alive and still maintained during more than 20 years (40 if you count its predecessor ex with its visual mode vi), it shows that such an application is robust and doesn’t get caught up by the new sleeky editors.

Vim’s powerfulness is due to its inner coherence. The letter `d` always has the signification: delete. The letter `w` means a word, so `dw` means delete the next work. `$` means the end of the line, so `d$` means delete to the end of the line. An abbreviation for `x$` where x could be any character is `X`. So `D` will delete all characters to the end of the line. In the same way `C` (change) will delete all characters to the end of the line and put you in insert mode (The mode that lets you use Vim like any other editor).

I’m trying to do the same with my own software. `j` and `k` are used to go up and down a list. What is very great about keyboard shortcuts is the following:

* They never take space on screen, delivering you the best experience
* They will go into your muscle memory, and you won’t need to look at the keyboard to go the next item in the list (just press the key with the little mark on it :-) )
* They make it possible to add functionality without loosing clarity: you don’t need to learn the keyboard shortcuts, but if you want to go one level up, you can.

Features : Value vs Cost

When you create a product, you’re probably discussing a lot about features. Here are a few possible questions :

Where should we put that button ?

Who should get access to that feature ?

How should we introduce that new feature (blog post, tutorials, …) ?

How should we implement that feature ?

There are probably much more questions you can ask yourself when you think you’re going to implement a feature.

However, one question that is essential and often not asked is the following one :

Should we add this new feature at all?

I think most of  the time, the answer should be No.

This is because how costly features are. I have tried to set up a few questions that you can ask yourself the next time you’re thinking about a new feature, to help you balance the value/costs of a feature.

Value

  • Will your customers use that feature often, or is it very useful even if it is not used very often ?
  • Does your software sell better if the feature is present ?
  • Will the feature benefit to many customers ?
  • Are you the only one to provide that value ?

Costs

  • How long will it take for you to develop that feature ?
  • Are there bugs in your software that you will take longer to fix because you will be busy working on the new feature ?
  • Are there pending support tickets that will still be pending because of the new feature development ?
  • Will the feature you’re building increase complexity ?
  • Is it easy to drop that feature if it doesn’t fit to the customers needs ?
  • What will be the cost of maintaining that feature ?
  • Is the new feature likely to add a security leak ?

Hope that helps !

 

You don’t need to be scalable from day 1

I see so many developers asking themselves the following question :

How should I write my code so that it will work if the traffic explodes ?

I believe thinking about this from day 1 is counterproductive. Here’s why :

Most of the time, you aren’t going to scale

Yes, that’s a truth, 99% of the projects will never have to scale. Some of the projects will die, others will just reach a certain amount of users and stay stable from there. Thinking you are part of those few organizations that will scale is an illusion. Furthermore, most of the time, you’ll see when you project is starting to get more traffic. When you know this, you will be able to adjust the size of your team. It is faster than ever to change the size of your team.

The overall speed of your growth is defined by the limiting factor

I went to a generalist engineering school, so I’ve done a bit of chemistry too, and here’s what I learned from that :

If one crop nutrient is missing or deficient, plant growth will be poor, even if the other elements are abundant.

Liebigs Law

Applied to start ups, this means that you can’t scale your business if you just make your application technically scalable. There’s customer acquisition that is very often a limiting factor, but also other bad conversion rates between the acquisition and the revenue.

They are some cases when your app’s design is the limiting factor of your growth, but in this case, you probably know it yourself (because your app is slow, customers give bad feedback , …).

Support is one of your main marketing channel

At beequick, our top priority is answering to support tickets/incoming mail. When a customer asks us something, we try out best to answer in the following hours. However this is not the case everywhere.

The current state of support

I have seen many companies where the employees would say:

This is Tom’s problem, he has some holiday, so I won’t answer that ticket.

And the ticket stays unanswered for a week or more. What a nonsense !

An other problem appears when separating the support team from the development team. Rule number 5 of Six simple Rules states:

5. Extend the shadow of the Future

What does that mean ? It is about responsibility.

If the people who build your stuff are not as well responsible for the support, your developers will not care if the product gets better. If your developers are not responsible for support, the customer feedback loop is broken. This feedback loop ensures that requests of your customers are getting implemented in your product. The customer feedback loop is one of the most important feedback loop in business, especially in the start up environment.

Put your customer’s requests first in line

I don’t have data to prove it, but from experience, I have always felt that customers who get quick answers are more loyal than others. Often a first support ticket that was answered quickly can trigger a purchase from the customer. For example, that’s what triggered the buy process when I first got a response from the support guys at fortrabbit.

It makes your product more valuable

A reason I’m never going to buy again from DELL is their poor support. 2 years ago, I booked a computer on their site, but I never received it. I had to speak hours over the phone with different persons who would never listen to me. They had standard problems they were able to solve, but anything outside of the standard was too complicated for them. I finally got my cash back but without any hassle.

When on the contrary, the support you get is personal, friendly and fast, you appreciate the product even more. It humanizes the product.

Having great support at the beginning doesn’t cost much

At the launch of your product/startup, you should try to do as much support as possible. Don’t try to hide the support button or make « premium paid support ». Support will bring you a lot of:

  • Valuable feedback from real customers : what do they like/dislike, where do they have difficulty to understand your product, what is important to them and what doesn’t matter
  • Trust : when trying a new product that just launched, you just don’t know if the product will still exists 6 month from now. Having spoken with someone about the product will at least give your customers more confidence.

Don’t eliminate support when you become bigger

When companies get bigger, they try to reduce their support budget. The reason for this is the scale argument : we are currently scaling our business, so we’re reducing costs. However, if you’re in the service business (almost everyone nowadays) , support is still one of the core component of your value. If you don’t continue to have nice support, your company will lose in trust, and thus in revenue.

Here’s a great article form Signal vs Noise about why they put everyone at their company on support.

Why docxtemplater is so awesome to generate docx files

I’m creating a library on Github, which is obviously open-source. The library creates docx from a template with data, much like what you’re used to do for HTML with templating languages like Mustache, Twig (for PHP), HAML (Ruby and Node), Jade (Node). The library is called docxtemplater and is specifically for docx. Docx is a format used by Microsoft Word 2007+. The library was named docxgenjs at the beginning. But I’m opinionated and only want to generate docx from templates. So I have decided to rename the library to docxtemplater. I have also removed the JS suffix. In fact, the library is not deeply linked to javascript as there is a command line interface (CLI). The CLI makes it possible to use the library from any language.

They are two main differences between HTML and Docx. This differences make it difficult to use one of the mainstream templating languages for docx:

  1. Docx is a zipped format, so if you want a solution that works out of the box, you should at least add a way to unzip and then rezip the document. You will also have to write the logic to modify the right files.
  2. Docx is made of xml, and the text is splitted around in the document. For example writing « {tag} » in a word document often results in the following code structure in XML:


<w:t>{</w:t>...<w:t>tag</w:t>...<w:t>}</w:t>

This makes it almost impossible to use a « normal » implementation of a templating language.

The library can process variables, but also loops, conditions, custom parsing of variables (with the angular syntax), and replace images.

Why narrowing to a docx templating system ?

I have a big problem with all other libraries that try to solve similar problems: They all involve that you should write all the document’s content in your application code. This seems very inefficient to me. Why the heck should I write static paragraphs inside my code base ? It has been a long time now that the whole software industry agrees that it’s better to use templates to generate HTML rather than echo out stuff in your application. However, this specific problem seems to have been developed with old standards. Yes maybe, you might want to get some super power and insert a very complex thing in your document (eg something that is not some text nor some image). But even if you want that, I created a syntax that allows you to insert some custom XML: {@tag}. If you want to insert an XML tag that is not possible to generate using normal tags, use the XML Tag. But please, avoid making the same mistakes again, eg don’t put all your static content in your codebase, that’s exactly what templates are for !

Even better, if you use templates, you will find it much easier to switch from one output type to an other, because all of the output types will share the data (but obviously not the template).

There’s still one bonus using the templates: Everyone can edit Word templates, but only a developer can change code that echoes out part of the docx. So using docxtemplater rather than an other library will let you as a developer do the data-binding, and your manager/whoever can create the docx template.