There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

On any given day, you will probably find my colleagues and me in the office, deep in discussion on how to best name for a certain method or variable. Maybe around evening, we’ll finally agree to disagree and just make a judgement call because, hey, we still need to ship our code by tomorrow.

Finding a good name isn’t a trade off between project management deadlines and programmers’ preferences. Naming isn’t just about technical conventions. Naming serves the practical purpose of handing over maintainable high level code to other development teams (i.e. for our clients) and quality APIs for our open-source serverless platform. A decade ago, before technical advances like WiFi, mobile, and cloud computing, our serverless platform was only a dream. But some things don’t change after a decade — things like how you choose a good name. So I’m just rehashing what we developers have known since Java, C, or even BASIC.

Symbols vs Names

Naming things in computer science is about giving a name to a concept. The concept can be common software design pattern like Singleton and Factory, or it can be a custom logic that we write code for. By giving a name to a concept, we make the concept concrete by defining the assumptions, the behavior, and the responsibility of the concept. A concept with a name is contained and no longer (as) vague.

Well, in theory, names aren’t needed — a symbol can also denote a concept. For example, in mathematics “+” (plus) or “=” (equal) are so well understood that giving them other names would just complicate things. If you love expressing things in symbols, maybe it’s time to get a pure maths degree. Programming is more than mathematics. How are we going to program using only symbols without looking up a textbook of documentation?

In programming, rolling your eyes is better than scratching your head.

That’s why naming is important: it helps to communicate a concept to another person (which can also mean your future self). When writing code, we want to focus on the logic without constantly breaking up our train of thought by looking up the documentation. During discussion with other developers, for example team members who rotate into a project, we want to refer to concepts without explaining its behavior all over again.

Therefore, a good name is a name that helps us communicate effectively.

• Obvious — the concept is apparent just by reading the name
• Unambiguous — the name is only associated with one concept, or that it is obvious the name is associated with a particular concept
• Accurate — the name is correct in describing the concept
• Consistent — the name follows certain convention or uses the same vocabulary to describe similar concepts

Follow Conventions

Let’s say we have a function called getAccessToken() . What could it do? Almost anything, like...

 ... returning an access token

 ... fetching the access token from underlying storage to get access token

 ... check with the server if the access token is still valid, and log the user out if the session timed out

 ... result in time travel

How do we know? The documentation should cover the implementation of the function, but it is not a good idea to constantly rely on documentation to deliver the meaning of the concept. It is one thing for a concept to be difficult to remember if we were to use a symbol, but it is very bad if the name doesn’t accurately convey the meaning of the function.

Convention is important here. Convention tells you what the get, or lack of get, actually means. If this function is part of a Java program, get tells you this function is a getter and should have no side effect. This convention is prevalent even outside Java. Convention in some languages discourage the use of get in name, but a function can still be considered a getter and should have no side effect.

Being consistent means that if you use the name get in your function, you should implement the function with no side effect, which is what most developers expect when they call your function. They also expect your function to return quickly because they expect the function to simply return an internal state.

Don’t Use the Same Name

A good name isn’t good if it only factors in one or two principles in naming. For example, when we designed our data model for our serverless Chat SDK, we called our model for storing information related to a conversation…obviously, Conversation. Conversation is a good name, because it is obvious that this model encapsulated information about a conversation. Since this is most commonly used as a noun, there isn't much room for mistaking a thing for an action.

But as we were writing the code for our API, we needed to name another model that stores user-specific information of a conversation. It would be used, for example, to show a message unread count to the user for each conversation they’re a participant in. In database schema design parlance, this model is an associative entity storing the relationship between user and conversation, with association relation attribute like unread count. The convention is to name this model UserConversation (or user_conversation as a table name).

Independently, both Conversation and UserConversation are good names. However when both models are exposed in the API of the Chat SDK, two good names equals one bad combination. Our most frequently asked question by Chat SDK users was: What is the difference between a Conversation and a UserConversation?

Sometimes You Need to Break Grammar Rules

Conventions often say our name should be grammatically correct, but we sometimes need to break the grammatical rules in order to make our code readable and obvious.

var somethings []Something // somethings? this word doesn't exist!

No one knows what “Something” is, but one thing is painfully obvious: “somethings” is a collection of values with the type “Something”.

Code should be obvious, even if we need to break some grammar rules to get there. If the grammar rules get in the way when we try to make something as readable as possible, we will always strive for obviousness rather than correct grammar rules.

We can also call the variable “arrayOfSomething”, but this will not be as readable as simply “somethings”. I am not saying that “arrayOfSomething” is bad naming. It is a good choice to make the type of the collection obvious.

“Settings” is another example we encountered in one of our client projects. In English, we always use the word “Settings” to refer to configurations while the word “Setting” refers to a situation or circumstance. However, in programming convention, we add “-s” or “-es” to represent multiple items of something. If we call a unit of configuration as “Settings”, how should we call an array of such “Settings”? “Settingss” is just too odd and will not pass our pull request review.

That’s why we code like this:

type Server struct {
    Settings []Setting // an array of Setting
}

That’s all I can think of for now. Give me a drink, and my memory will come back with more examples. In fact, some of our best exchanges and breakthrough ideas have come from ad hoc tasting sessions at our DIY whiskey corner.

The great thing about having fresh graduates working with developers who have 10+ years of experience is that we are constantly reminded about how readable our code is.

I’d also like to thank my Skygear.io colleague, cheungpat, for his input and helping me edit this piece.

Building an app? Our free developer tools and open source backend will make your job easier.

Naming 101 was originally published in Oursky Team on Medium, where people are continuing the conversation by highlighting and responding to this story.

Scenario: Shoebox or social app?

Say you’re a developer who wants to build a note taking app. Let’s look at one feature detail with huge implications on your back-end. To write a note, your app will need to be able to save the data.

Saving a record to a database is straight forward. The key questions are:

• Who will need to access that record?
• Will it only be your user, or will your user share it with others?
• Will your product be shoe-box app or a social app?

If you intend for the notes to be private to the author, you may conclude that you are making a shoe-box app. This means all data goes to a private DB (database).

If you intend for your app to share notes with others, you may conclude it should be a public DB.

But will you know which it is before you start?

And what will you do if you need to change your product as you go? Public DB and private DB isn’t the first thing most developers think about when they’re building an app. We encountered these question when we were building our back-end product for our developers, Skygear.

Because of our experience in building apps for clients, we assumed there was a right choice of database. And that our user would know how to choose.

How do you build a back-end for developers who aren’t sure of their products needs yet?
Or for those who want to keep their options open in the future?

As the tech lead in the project, I’d like to share with you our decision making process from 2 years ago. I hope it helps future development teams approach unknowns and assumptions.

Why did we start thinking about private vs public DBs?

Many apps require a back-end to store and query user data. The back-end is a lot of hard work to build and, let’s face it — not so enjoyable to create. Skygear is our open-source serverless back-end. It helps address common development features for mobile and web apps.

The feature I’ll talk about is our Cloud DB, where you store and query user data. When we started to design Cloud DB, we asked ourselves how different apps store and query user data.

We looked at our company’s mobile apps portfolio for inspiration. Our company does everything from consumer apps to e-commerce apps. So we grouped them into “shoe-box” and “social” apps.

Shoe-box apps store personal data that the user wants to keep private. For example, our side project Spentable helps a user track of their daily spending. Data stored in the app is meant to be private, in a shoe-box.

But, there is stuff that we want to share publicly or with friends. That also means the user needs to be in control of who can read their data. These two kinds of apps present a challenge in how we designed Skygear’s Cloud DB. We wanted to make storing data in Cloud DB as easy as possible. For shoe-box apps, all the developers need is a database where each user can only see the data that they are putting in. Yet, in social apps, developers need features such as ACL (access control). How can we make things simple for developers of both kinds of apps?

Having our cake and eating it too

We decided to solve this problem by introducing the concept of multiple databases in the Cloud DB: private DB and public DB. Each user has a private DB to put data in, and that data is only available to the same user. The app also has one public DB that is shared among all users.

A shoe-box app developer is able to focus on saving and fetching the data without worrying about permissions because data in the private DB is always private.

But, private DB does not work at all for social apps. Developers for social apps should put data in the public DB because data in social apps are meant to be shared.

Before we added support for ACL, this simple distinction for public and private data served us(and our users very well. Everything in private DB is truly private while everything is public DB is truly public.

“Everything is public” is not good enough. Most social apps have use cases that data is only shared among a group of friends.

ACL is another difficult and interesting topic that should be it’s own article.

We couldn’t have the best of both databases

Separating the DB into private and public ones was a good idea. We thought they supported the use case for majority of apps.

But early adopters found our private and public options confusing.

Our early users gave us invaluable feedback. We also paid attention to the support questions we received. This is what we learned from developer feedback when they used our Cloud DB:

1. It’s not obvious to developers what they’re building at first
   While it may be obvious which kind of app developer made by looking at the product retroactively, it is not obvious from the get-go. Forcing the developer to decide whether they are making a shoe-box or social app at the beginning is difficult, if not impossible.
2. Developers just want to get started quickly
   We want the developers to learn the basics as quickly as possible. Having to learn one more concept to choose which DB to use before they can actually save and retrieve data is too much to ask for new users.
3. The decision for public or private DB, once made, isn’t easy to reverse
   Suppose that a developer started with a shoe-box app idea and they put everything in the private DB. Later they may realize that they should make the app a social one instead. It is not easy to migrate data once they are put into a particular DB.
4. Permissions are usually an after thought
   Data security a priority in our company. But data security is not the first thing that comes to the mind of a developer. Especially when they’re just doing a proof-of-concept prototype. They want to focus on the functionality first, and take care of the security later on.

Our takeaways

We are always thinking about how we could make our products better. We could do better in terms of software architecture, user documentation and ease-of-use. We sometimes brainstorm what we would do if we could rewind the clock two years to start over. But here is what we would tell our former selves:

1. If developers are already familiar with an existing concept, adopt it
   Most developers are familiar with the concept of a database. It is a container of some sort where developers can save content. They can also retrieve data and support the CRUD (Create, Read, Update, and Delete ) property.
   Because developers are already familiar with the concept of a database, they would find a single database on Cloud DB straight-forward to use.
2. Introduce new concepts when developers are prepared for them
   This idea is actually an other way of saying that we should make the learning curve as easy as possible. Skygear was a prototype in its own way. We just launched V1.0!.
   You never want to make life for your early adopters difficult. Having to learn everything before developers can do anything does not work well from a product perspective. Until developers need to think about data permission, they should not need to know about the difference between a private DB and public DB. We should let our users get started with the common concepts first to familiarize themselves with a new platform.
   Only after they’re comfortable should we introduce new concepts to provide more options. In this case, there’s no harm for a developer to discover they need ACL so the new concept is a natural next step after they have learned how to use Cloud DB.

What we learned

When we began working on Skygear two years ago, we wanted to build a kick-ass product with 2–4 of our senior developers. We had ready testers from our own in-house developers, who gave lots of critical feedback. We thought we were using our experience in web and mobile app development to make better decisions on how to design tools for other developers.

But our experience also created assumptions about what to expect our users to know before using our product.

The good thing about getting user feedback on Cloud DB as we went was that we learned that our assumptions were incorrect. Our most valuable lesson was the humbling reminder of a basic startup principle. No matter our experience, we often don’t know exactly what we’re building.

Of course, that doesn’t stop us from trying to build that philosopher’s stone to make lives easier for our fellow developers anyway. As my co-founder, Ben, said one of his most productive days was when he tossed 1000 lines of code away.

I would like to credit my colleague cheungpat who worked on the Cloud DB with me and helped write this piece.

My team would love to hear your critical feedback for Skygear. Also check out our documentation and GitHub repos to see how we discuss Skygear features.

How to handle unknowns and make assumptions when designing a cloud database was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

In a company that makes mobile and web products, developers shouldn’t be the only ones who can launch the latest version of an app. You need proper testing beyond getting colleagues to give ad hoc feedback by clicking through the app.

At Oursky, our QA built an automatic testing pipeline. But testing needs to be coordinated and the report needs to go to the relevant people. The QA team needs to know when to test the latest version of the app. The PM needs to check the latest progress. And the designer needs to support and fine-tune the details. While building command line tools is the obvious go-to for developers, we wanted to find a tool that everyone in the company uses.

We created our deployment ChatOp on Slack. Read on to see how you can do it with your chat service. You can automate your deployment, which saves everyone time and reduces coordination errors (Campfire, Hipchat, and Flowdock are also supported). We’ve been using ChatOps in 15+ simultaneous projects within our team.

ChatOps is a great way to make the deployment procedure less complex, less black-boxed, and less scary.

I adapted GitHub’s use of ChatOps for our deployment with Slack. GitHub’s open source chatbot (Hubot) does automating deployment, graphing, monitoring, provisioning, tweeting, and many other things. GitHub even created MySQL database back-up jobs so they can do important operations without leaving the chatroom with a set of instructions.

The big picture of ChatOps deployment

ChatOps simplifies deployment with automation: it removes manual coordination errors, and allows everyone in a project to jump in. It also encourages open communication so team members don’t have to interrupt each other for updates or documentation. They can access information whenever they need it.

So how does it work and how do you set it up?

This graph shows how deployment interactions would work via Github.

Our company implemented a similar version using open Slack channels for all our operations. Each project has its own channel. We introduced two Slack botsk, Chima and Faseng, to assist the deployment process. (Chima and Faseng are the names of our resident office cats.)

The core idea is summarized in this sentence:

Tell Chima(CEO), to make Faseng(CTO) deploy.

Roles of the bots: Creating & executing

For each project, we set up respective deployment jobs with Faseng. It’s not only easily to deploy, but deployment notifications make the progress and status of the project clear.

Creating the deployment job (chat command bot)

Chima is a github/hubot which helps to understand our commands from Slack. For example chima deploy is a deployment command.

We have to configure these settings for each project:

• Specify a deployment provider such as Fabric, Capistrano, Heroku, or any Ruby Rescue task
• Whether to support auto_merge for the target branch for deployment
• The repository name of the project
• Available environments of the deployment
• Only channel members in the allowed_rooms list can create the deployment

We put this configuration in the app.json file. Below is an example of how you can configure for project-x:

{
  "project-x": {
    "provider": "fabric",
    "auto_merge": false,
    "repository": "oursky/project-x",
    "environments": ["live", "edge"],
    "allowed_rooms": ["deployment"]
  }
}

Executing the deployment job (deployment bot)

Faseng is an atmos/heaven program. When it receives GitHub webhooks, it will run deployment jobs as background tasks with Resque. There are several supported ways to create deployment jobs, such as:

• Fabric
• Capistrano
• Heroku
• Any Ruby rescue task
• Lita: Written in Ruby
• Err: Written in Python

Deployment task creation and completion will send out notifications into the integrated chat services. Campfire, Hipchat, SlackHQ, and Flowdock can receive deployment status event notifications.

Use cases in our company

1. Developers use it to deploy to the staging environment

Although we planned to use ChatOps to ease the difficulties for non-developers, it also benefits me as a developer.

For example, when I want to deploy trellhub/edge to pandawork, I can just type chima deploy trelhub/edge to pandawork and then brew some coffee while I wait.

To deploy using a chat command, I have to set up the environment settings at Chima. To make sure the deployment is authorized, I have also provided Faseng the access to the pandawork server.

2. QA can also deploy the latest version to the edge

After each milestone, the QA team is responsible for performing functional tests, usability tests, and performance tests for the pre-deliverable software.

In this example, our QA engineer, Joyz, wants to ensure that the latest version of modmod-web is ready on the edge environment before she runs the tests. She can trigger the deployment and receive notifications as well.

3. Checking up the current jobs

To see the current building jobs, everyone who is relevant to the project can talk to Chima and check on the Travis building progress.

This one-time initial ChatOps setup has helped our team manage our projects in the following ways:

• Enables less technical members on the team to contribute to the development process.
• Notifications are pushed to the relevant project channel, which means that every relevant team member receives and can access status updates.

We are working towards doing more via ChatOps , such as backing up servers and performing automated tests. Look out for future updates or share your tips with us! We’d love to hear from you.

Further reading

About continuous integration

• Issue 6: Build Tools · Issue Travis CI for iOS

About deployment

• Github Developer — Deployments
• Remote multi-server automation tool — Capistrano
• Python tool for streamlining deployment- Fabric

Footnote: Now, we’ve moved to GitHub trigger deploy.

Building an app? Our free developer tools and open source backend will make your job easier.

Liked what you read? Give me some claps so more people see this article! Thanks!

Want to make the deployment process less scary? Build ChatOps in Slack. was originally published in We’ve moved to freeCodeCamp.org/news on Medium, where people are continuing the conversation by highlighting and responding to this story.

In this post, we are documenting how we used Google’s TensorFlow to build this image recognition engine. We’ve used Inception to process the images and then train an support vector machine (SVM) classifier to recognise the object, in other words, transfer learning. Our aim is to build a system that helps a user with a zip puller to find a matching puller in the database. This piece will also cover how the Inception network sees the input images and assess how well the extracted features can be classified.

Our puller project with TensorFlow

Recently, Oursky got a mini zip puller recognition project. One of our teams had to build a system for users to match an image of puller with most similar puller inside the database. The sample size for the trial is small (12 pullers), which has implications discussed below as we share our experience on trying out Google’s TensorFlow.

Our first test was to compare the histogram of oriented gradients (HOG) feature computed on the input image and all the puller model images rendered from their computer-aided design (CAD) models. This solution works but the matching performance is poor if the input image background has a strong texture.

We also tested an alternative solution to address the problems with the textured background. We then built a relatively shallow convolutional neural networks (CNN) with 2 convolutional layers and two fully connected layer [1] for classifying the puller image. However, since our data set is too small (around 200 puller images for each type) and lacks variety, the classification performance is poor. It is basically not different from making random guesses.

Training a CNN from scratch with a small data set is indeed a bad idea. The common approach for using CNN to do classification on a small data set is not to train your own network, but to use a pre-trained network to extract features from the input image and train a classifier based on those features. This technique is called transfer learning. TensorFlow has a tutorial on how to do transfer learning on the Inception model; Kernix also has a nice blog post talking about transfer learning and our work is largely based on that.

Brief overview on classification

In a classification task, we first need to gather a set of training examples. Each training example is a pair of input features and labels. We would like to use these training examples to train a classifier, and hope that the trained classifier can tell us a correct label when we feed it an unseen input feature.

There are lots of learning algorithms for classification, for example SVM, random forest, and neural network. How well a learning algorithm can perform is highly related to the input feature. Input feature is a representation that captures the essence of the object under classification.

For example, in image recognition, the raw pixel values could be an input feature. However, using raw pixel values as input feature, the feature dimension is usually too big or too generic for a classifier to work well. In this case, we can either use a more complex classifier such as deep neural network, or use some domain knowledge to brainstorm a better input feature.[2]

For our puller classification task, we will use SVM for classification, and use a pre-trained deep CNN from TensorFlow called Inception to extract a 2048-d feature from each input image.

Bottlenecks features of deep CNN

The common structure of a CNN for image classification has two main parts: 1) a long chain of convolutional layers, and 2) a few (or even one) layers of the fully connected neural network. The long convolutional layer chain is indeed for feature learning. The learned feature will be feed into the fully connected layer for classification.

The feature that feeds into the last classification layer is also called the bottleneck feature. The following image shows the structure of TensorFlow’s Inception network we are going to use. We have indicated the part of the network that we are getting the output from as our input feature.

How Inception sees a puller

Training a CNN means it learns a bunch of image filters (kernels).

For example, if the input of the convolutional layer is an image with 3 channels, the kernel size for this layer is 3×3 and there will be an independent set of three 3×3 kernels for each output channel. Each kernel in a set will convolve with the corresponding channel of the input and produces three convolved images. The sum of those convolved images will form a channel of the output.

The illustration below is a convolution step.

As the output of each convolutional layer [3] is a multi-channel image, we could also view them as multiple gray-scale images.”. By plotting those grayscale images out, we can understand how the Inception network sees an image. The following images are extracted at different stages of the convolutional layer chain The points are illustrated as A,B,C and D in the Inception Model figure.

This is an input image.

All the 32 149×149 images at stage A:

All the 32 147×147 images at stage B:

All the 288 35×35 images at stage C:

All the 768 17×17 images at stage D:

Here we can see the images become more and more abstract going down the convolutional layer chain. We could also spot that some of the image are highlighting the puller, and some of them are highlighting the background.

Why is the bottleneck feature good?

The bottleneck feature of Inception network is a 2048-d vector. The following is a figure showing the bottleneck feature of the previous input image in bar chart form.

For the bottleneck feature to be a good feature for classification, we would like the features representing the same type of puller to be close (think of the feature as a point in 2048-d space) to each other, while features representing different types of puller should be far apart. In other words, we would like to see features in a data set clustering themselves according to their types.

It is hard to see this kind of clustering happened on 2048-d feature data sets. However, we can do a dimensionality reduction[4] on the bottleneck feature and transform them to a 2-d feature which is easy to visualize. The following image is the scatter plot of the transformed feature in our puller data set[5] . Different puller type are illustrated by different colors.

As we can see, the same color points are mostly clustered together. It has a high chance that we could use the bottleneck feature to train a classifier with high accuracy.

Code for extracting inception bottleneck feature

The inception v3 model can be downloaded here.

Training a SVM classifier

SVM is a linear binary classifier.

The goal of the SVM is to find a hyper-plane that separates the training data correctly in two half-spaces while maximising the margin between those two classes.

Although SVM is a linear classifier, which could only deal with linear separable data sets, we can apply a kernel trick to make it work for non-linear separable case.

A commonly used kernel besides linear is the radial basis function kernel (RBF kernel).

The hyper-parameters for SVM includes the type of kernel and the regularization parameter *C*. If using the RBF kernel, there is an additional parameter *γ* for selecting which radial basic function to use.

Usually the bottleneck feature from a deep CNN is linear separable. However, we will consider the RBF kernel as well.

We used simple grid search for selecting the hyper-parameter. In other words, we tried out all the hyper-parameter combination in the range we have specified, and evaluated the trained classifier performance using cross validation.

The rule of thumb for trying out the *C* and *γ* parameter is trying them with different order of magnitude.

We used 10-fold cross validation.

SVM is a binary classifier. However, we could use the one-vs-all or one-vs-one approach to make it a multi-class classifier.

It seems a lot of stuff to do for training a SVM classifier, indeed it is just a few function calls when using machine learning software package like scikit-learn.

Code for the training the SVM classifier

SVM training result

The following is the training result we get, which got a perfect result! Though this might deal to overfitting…

We’ve used it to built an mobile app and a web front-end for the puller classifier for field testings.

Since the classifier can work with unseen samples, it seems that the over-fitting issue is not so serious.

Conclusion

A pre-trained deep CNN, Inception network in particular, could be used as a feature extractor for general image classification tasks.

The bottleneck feature of the Inception network should a good feature for classification. We have extracted the bottleneck feature from our data set and did a dimensionality reduction for visualization. The result shows a nice clustering of the sample according to their class.

The SVM classifier training on the bottleneck feature has a perfect result, and the classifier seems to work on the unseen sample.

Footnotes

1: ^ The model is based on one of the TensorFlow Tutorial on CIFAR-10 classification, with some twist to deal with larger image size.

2: ^ Sometimes, it will be the other way round, the dimension input feature is too small, we need to do some transformation on the input feature to expand its dimension. The process of picking a good feature to learn is called feature engineering. It is a difficult task. One of the reasons why deep learning is so popular is because we can feed in raw and generic input to the network, and it can automatically learn some good feature during the training. However, the trade-off will be a huge training data set and long training time.

3: ^ Noticed that one convolutional layer is not just having one convolution operation, it could also have multiple convolution operations, pooling operations, or other operations.

4: ^ The algorithm for dimensionality reduction we use is t-SNE.

5: ^ We didn’t use the full data set for the classification, instead we remove images has low variety from the data set, this result in a data set of around 400 images.

If you find this post interesting, please click that heart below so other people can see too!

Building an app? Our free developer tools and open source backend will make your job easier.

Originally published at code.oursky.com on October 21, 2016.

How to use transfer learning to create an image classifications engine was originally published in Oursky Team on Medium, where people are continuing the conversation by highlighting and responding to this story.