Code

Version Control

Involution frequently develops software as part of a client engagement. This might be code for an internal project, a prototype for a client, or production code for a client. Using version control is a studio requirement for any project involving software development

Before Creating a Repository

There’s a few things to consider before creating a rpository. Primarily, based on information from early meetings and interactions with the client, we need to determine whether the code lives in one of our repositories or needs to be in theirs.

Client Hosted Version Control

If you are working with a client, ask the client if they prefer that we use their version control system (VCS). A client may need us to work with their VCS due to the proprietary nature of their software, privacyobligations to their clients or members, or myriad other reasons. If this is the case, follow up with the client contact on how to gain access to this system, any documentation they may have on their VCS or process, and possibly a good time to get a walkthrough of their process. In this case, the client will need to create a repository for us to work with.

Invo Hosted Version Control

If the project you are working on is internal or the client does not request that we use their version control system, we will use a git repository hosted at Github. This should be our preferred way of working, so we can offer a consistent experience from client to client and project to project.

Some other useful questions to ask up front include:

Creating a Repository on Github

Github has some good documentation on how to create a repository. Here are a few things to note.

(If you’re using Github for Mac you can use CMD+N and proceed as outlined at the URL above)

Private vs Public

Because of Involution’s commitment to open source software, we default repositories to be public whenever possible. When working on an internal project, quickly double-check with the powers that be whether it is okay to make the repository public. Always check with the client before creating a public repository on their behalf.

Open Source Licenses

If the repository is public, make sure to include a License. We generally use Apache 2.0, but check out this site from Github for some help.

Naming Conventions

When naming a repository on Github, make the name Pascal case (camel case with the first letter capitalized).

Client Repository Names

The repository name should start with the client’s name and contain their product name (when relevant) as well as the project. Below are some examples:

Internal Project Repository Names

For projects that are owned by Invo, it is not necessary to include Invo in the repository title. In this case, give the repository a name which describes the software as a product. For example:

Access

Git Workflow

Branching and Merging

We generally model our branching and merging strategy for projects off of the model outlined in this article. Unless you have a strong reason to deviate (i.e. a client prefers a different workflow or you aren’t using git), you should probably use this workflow.

Releasing Source Code

Whenever you release source code to a client, or push it to a production server, you should tag that release in git. It is tedious to tag releases, but it is almost always a good idea. If there is some sort of additional work done as part of a “release” (i.e. adding .mobileprovision files or packaging an iOS application as an IPA), use the release functionality of Github to upload those extra dependencies.

Evaluating APIs

These are some things we should check for when reviewing APIs to provide feedback.

URL

Request/Response Data Structure

API Functionality

Workflow

Tips on Communication

Other Useful Tools

Validating APIs

When developing and debugging API based applications it is sometimes useful to test the API independent of the UI codebase. There are a few tools which help make this possible:

Postman

Postman provides a free Chrome extension which lets you execute HTTP requests from your browser. At its core, it is an in-browser wrapper for curl. A few things to note that makes Postman especially powerful:

If you are having trouble making an API request within your application, it is useful to try to test it from Postman. This can isolate whether it is an issue with your code or an issue due to CORS configuration.

Charles

Charles is a cross-platform HTTP monitor and proxy. It will capture all network traffic on your computer and allow you to inspect the individual HTTP requests that are being made by your application. A few notes:

Chrome Developer Tools

I find that the Chrome Developer Tools are feature rich and friendly than the Safari or Firefox developer tools. There’s a bunch of documentation online about how to use them.

Creating UML Diagrams

A UML Sequence Diagram is worth a thousand words (or an hour on the phone). They can very quickly show high level concepts of communication as well as surfacing the details. UML Class diagrams are also really useful for showing relationships between objects.

Formatting and Validating JSON

Scraping Data from Websites

Sometimes, you might want to scrape data from a website or web request to look at it more closely. Here are some techniques for doing so: