Report on MadCode Meetup by Stanfy

Last Thursday we conducted our first Stanfy MadCode webinar and below we’ll talk a little bit about it to let you know how it was and what would be next.

The main goal why we organized this event is to share our strong experience in mobile development and initiate a tradition of promoting dev meetups in Kyiv.

The first MadCode Meetup was dedicated to effective interactions between mobile and backend developers to find the ways of productive communications with the latter not spending their time on finding who made errors but rather building great products together.

This problem is quite common when mobile and backend developers are separated by distance and time zones and email communications become longer and longer, but the problem stays unaddressed. From this perspective, Anastasi Voitova opened a series of MadCode webinars and shared useful tips to help you avoid unproductive communications with backend developers.

Usually, mobile applications are composed of a mobile app itself (actually that one you can download from the AppStore or the GooglePlay) and backend server, which stores data and handles some complicated logics to operate that data. Also, as a rule, (though there are some exceptions) there are two developer teams: mobile and backend, which interact with each other to build a handy high-quality product. And on some occasions, quite often unfortunately, those interactions are poor.

From mobile devs’ perspective, a list of the following tips is important for sound app-server communications:

• fewer requests (frequent requests cause fast battery draining)
• low latency (the user shouldn’t see loading spinner too long)
• transfer only needed data (sending too much data bits increases bandwidth usage, takes long times and drains battery)
• transfer data in a suitable data format
• perform heavy computations on server (mobile devices still have lower performance than server computers, it’s criminal to waste the user’s time and to make him/her wait)

Backend devs can ensure such server behavior if they are motivated (and skilled) enough. However, sometimes motivation is low, because of a misunderstanding or an existing limited experience in other technical areas. Server devs rarely think about requests from the perspective of saving mobile battery life, and mobile devs rarely explain the importance of the latter.

Communications in the right manner can increase motivation and build trust between teams, which leads to a better product quality.

We reviewed some approaches to build a successful communication pattern — of course, if there’s no way just to go out for a beer —, which includes:

• develop API documentation
• write tests
• compose constructive emails
• explain on examples

Documentation

In a perfect world, all server-mobile devs communications could go through documentation.

Actually, documentation is a great thing. It allows for concentrating knowledge about the system in one place and always use it to resolve problems.An important notice: documentation has to be shared between everyone on the team, identify the behavior uniquely and always to be kept up-to-date.

Documentation could be a rather simple API doc or a business logic description, anyway it should be written in a plain language and be easy to navigate.

It’s great when the server developer uses some documentation generator. It’s also fantastic if you have an opportunity to create a wiki for specifications. Otherwise, use  Google Docs, they are ideal for lazybones: easy to create, easy to share and easy to edit. That’s all. Use GDocs if documentation crafting sounds too complicated for you. We have shared GDoc with basic documentation sample, feel free to use it.

Well, it’s not enough just to create docs. Navigation through documentation should be also easy and handy enough. You should create a revision history table (or use edit/commit history in wiki) and note every change there: who, when and what is changed. Add links into the description for objects you’ve changed: it’s always easier to click-and-open than to scroll-and-search. Also, take care about structure: contents is another must-have feature.

The next step is to add some fundamental things to docs. They are the things that won’t change even if a huge meteor crashes into Earth (well, maybe except for this case). These things are as follows:

• production/staging server URLs (in case of amnesia)
• main accounts with passwords (for web, for iOS, for android versions of app)
• current API version (nice to add it into base URL or HTTP headers)
• usual request format (f.e. POST body encoding)
• usual response format (json/xml + validation rules, provide unified response structure)
• request/response encoding (utf-8 + gzip is usually enough)
• date format (like ISO8601 yyyy-MM-ddTHH:mm:ssZ)
• device information (add to HTTP headers: device platform, app version, image scale, etc)

It’s nice to add common HTTP response codes and describe app’s expected behavior (f.e. 401 HTTP code cause login screen to appear because session is expired).

We also add inner error codes, that allows us to customize app behavior making it more flexible (f.e. inner error code that shows to sync DB or just to show some messages to the  user).

API tests

API tests are also an indispensable way of communicating: they document server behavior in a more define manner, reflect the real state of implemented features and allow us to find ordinary bugs.

There are some must-have features for tests:

• up-to-date
• shared with the whole team (both backend and mobile team should have ‘write’ access, should update and use tests)
• automated run (f.e. run tests on every deploy and every night)
• public testing results (easy to blame )

Usually, we create a separate git repo for tests and build them on the Helium framework.

With Helium it’s necessary only to write declarations (objects, requests and responses), Helium will generate poke tests itself. Also, Helium allows us to write complicated scenario tests and generate models on Java for Android (generation on ObjC for iOS is coming).

Miscommunications

Tests and docs are good concrete ways of communications. Emails, on other hand, are not. We use emails because of time zone differences, or when we don’t want to waste time on face-to-face meetings.

There are a score of simple heads-up to make emails more useful:

• always provide enough info for bug reports in server implementation (timestamp, user ID/session ID)
• don’t copy long logs into an email (copy a small important piece and paste everything else into private pastie and provide URL)
• explain on examples (f.e. if you ask backend dev to add another field to response, it’s nice to show screenshots with app UI and explain why this particular field is really necessary for user)
• always update documentation with solutions that were provided in emails
• remember about different approaches (backend devs usually don’t have experience in our area, their approach is more DB-driven, while ours is design-driven)
• be thankful (politeness and appreciation improves communications)

Why do we care?

Well, at the end of the day we — mobile developers — are responsible for the app that the user sees. It’s we who usually gather feedback: no one write  a review — ‘your server is slow’, instead people write — ‘your app is slow’). That’s why we have more responsibility and more sense to make efforts to design our apps as an user-friendly product, which could be proudly called “just being awesome”!

Source: Stanfy