Heartbeat Cocoa

The native reference client for Heartbeat for OS X Yosemite.

Before you start…

Only designers are allowed to contribute to this code base. If you want to contribute to it, realise that you’re a designer. For every line of code you contribute, ask yourself: does this improve the experience of the person using Heartbeat?

If you believe that the experience of the person using Heartbeat is not your concern, please do not contribute to this codebase.

Conventions

Accessibility

Accessibility is not an afterthought or a layer; we consider it continuously at design and development time.

A feature is not complete and won’t be accepted until it is accessible.

We see accessibility as usability for audiences with special needs. These may be environmental, physical, or psychological in nature. They may be temporary or permanent. And they may vary in severity.

We also recognise that the needs of different audiences may be different and may even conflict with one another (e.g., high contrast text may aid people with visual challenges or people viewing the app in bright sunlight but may hinder comprehension for people with dyslexia).

Localisation and internationalisation

Localisation and internationalisation, like Accessibility (and related to Accessibility) are not an afterthought or a layer; we consider them continuously at design and development time.

A feature is not complete until it is internationalised and localised into the supported languages.

We are initially starting with one localisation (Turkish) as that is the foreign language I’m (Aral) fluent in, in addition to English. Others will follow.

### Views and auto layout constraints

Use Interface builder to lay out views

We use Interface Builder to lay out views and tweak constraints. The live preview is especially useful for testing localisation and responsiveness.

Please keep the storyboard(s) tidy and lay out your objects so that they are grouped logically.

We take pride in how the app looks on the inside as well as on the outside.

Give all views an Identifier

The convention is to name your identifiers so that if you had a custom class for the view, it would have the same name, written with the same capitalisation.

e.g., PreloaderView

This, among other things, helps when debugging constraint-related issues in Auto Layout as it produced nicer Visual Format Language strings.

Name all elements in the Document Outline view

Base the visual element name on its identifier/class name but use spaces so that it is easier to read.

e.g., Preloader View

Recreate constraints in code

However, we then recreate the constraints in code in the viewWillAppear method of View Controllers.

This involves:

Removing existing constraints: view.removeConstraints(self.view.constraints)
Setting up the constraints using Cartography.

At the cost of some repitition (of tasks, not code), we get the benefit of knowing exactly which constraints are affecting our views (and the ability to quickly alter them all from one place) while also maintaining the rapid prototyping and experimentation that Interface Builder affords us.

For more discussion on this, see the Labs post on Animating Cocoa Window Size When Using Auto Layout

Code consistency

We use:

Tabs not spaces
Curly brackets on their own line

White space and comments liberally to aid intent and comprehension. e.g.,

//
// Scale the Heartbeat balloon to full size. 
// (This is our launch-time progress indicator.)
//
layout (balloonImageView)
{
    /* as */ balloonImageView in

    balloonImageView.left == balloonImageView.superview!.left
    balloonImageView.right == balloonImageView.superview!.right
    balloonImageView.top == balloonImageView.superview!.top
    balloonImageView.bottom == balloonImageView.superview!.bottom
}

We code for intent and consistency and we do not prematurely optimise.

When in doubt, stick to the formatting you see elsewhere in the source. If you see a discrepancy, please flag it.

Remember these wise words by Brian Kernighan and P. J. Plauger:

‘Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.’

Common issues and troubleshooting

App crashes after repeatedly getting errors that Pulse has crashed.

Reason

Dangling Pulse process.

Workaround

Run the killnode script and restart Heartbeat.

Credits & license

Made with ❤ at [Ind.ie][4]

We are working on a license that is free as in freedom and yet allows us to publish and distribute Heartbeat on the App Store. In the meanwhile, we are releasing the code, all rights reserved, for review. To follow the updates, please see the Towards Ind.ie Commons Licenses thread on the Ind.ie forum.