Coding Philosophy and Best Practices

This evolving document contains our coding philosophy (general) followed by our best practices (specific and detailed). If you do not understand or agree with anything in the contents of this document, you should bring it up and discuss/debate it with fellow developers.

NOTE: THIS DOCUMENT IS A WORK IN PROGRESS. Some section titles are acting as place holders.

Software is an Engineering Discipline

We view software development as an engineering discipline wherein tradeoffs must be made between many competing “goods”. For example, there is a tradeoff between the cost to develop a piece of software and its reliability.

As engineers, we need to make these tradeoffs so as to maximize the value we deliver to our clients. Often this is difficult because the complexity and subtlety of the tradeoffs can be difficult to communicate properly to clients. In fact, in may respects, clear communication with the client about software problems is one of the most challenging aspects of being a software engineer.

Characteristics of Software Quality

Software has both external and internal qualities. External qualities are qualities that the client or software user would be aware of. Internal qualities are only apparent from the code (or perhaps data) itself. Of course, the line between these two is blurry, because internal qualities (e.g. no testing) will usually result in external qualities (poor reliability).

Here is a list of external qualities of a piece of software:

Here is a list of internal qualities of a piece of software:

There are certainly other ways to segment the “quality landscape”. This particular segmentation includes some overlapping categories.

Development Environment

Motivation

Setting up a development environment should be made as easy as possible. This is useful when you

Standard Script Names

These standard scripts make it easy for developers to manage their project environments and start being productive quickly:

All of these commands except run should be idempotent.

Note that not all of them are required. Also note that they are focused on development environments rather than production ones.

Test Data

The buildall script should create a minimal set of useful development data for new projects. This ensures developers don’t need to manually re-create data to test against.

Complexity

The primary object of software architecture is to manage complexity.

Documentation

There are several forms of documentation that go into a software project. Each form has its own place.

Comments

TODOs

A comment with the form TODO: Something I should address eventually are a standard format for indicating issues that should be addressed in the future. By using the same standard format, it makes it possible to grep through a code base and find accumulated technical debt.

Commits

Write good commit messages:

User-Facing

READMEs

Testing

Philosophy

There can be too many tests, although there are usually too few. Tests serve as live documentation for a codebase and provide protection from many accidentally-introduced bugs.

End-to-End Tests

Programmatic end-to-end tests are a common source of technical debt accumulation; they are expensive to write and age quickly. Written end-to-end tests are a good compromise. Write out a list of test cases in English with clear, specific instructions.

Code Reviews

All code should be reviewed by another Innolitics team member before being merged into the main branch.

Good code reviews take a lot of time for the reviewer, and while it may be frustrating to the author if there are delays, there are many upsides to reviews:

Code reviews are often the last step in achieving a milestone or customer deliverable. Reviewers should give code reviews high priority when scheduling your time, and ideally will be completed within a few hours of being requested.

Bugs are inevitable, and they are as much the reviewer’s responsibility as the author’s.

When reviewing code, check for:

Typically code reviews should happen inside Pull Requests so that the communication can be kept around for future reference.

Here is a collection of pointers for reviewers:

Whitespace

Lines SHOULD be shorter than 100 characters and MUST be shorter than 120 characters.

Technologies

We try to avoid prescribing too much about using particular technologies because conventions change quickly.

Choosing

Python

Follow PEP8.

Use Python 3 when possible.

References

Code Complete, by Steve McConnell, is about code construction. It is out-dated in that it implicitly assumes a “waterfall” development strategy and it does not discuss testing enough, however most of its suggestions are clear and relevant.

Clean Code, by Robert C. Martin, describes how to write clean readable code. Its suggestions overlap with Code Complete, but it is sufficiently different to warrant reading too. Some recommendations deal with Java-specific problems (e.g. the recommendation not to use arguments on class methods, and problems with argument ordering).