Company Practices

This document can be found at http://npxdesigns.com/guidelines/

Dear colleague,

Here are some guidelines which I strive to adhere to when doing software development, which I ask you to adopt as well for the sake of consistency and for providing the best outcomes both for NPX Designs and for our clients.

Test driven development

Though I’m not a maniac about it, I try to write unit tests first when possible, then write the code which passes those tests. This provides enormous security and freedom to refactor when needed, while encouraging modularity. Python doctests help make this practice straightforward and easy.

In-line documentation

End-user documentation is clearly important, but so is inline documentation (docstrings). The docstrings you write plus your unit tests will go a great way towards documenting the inner workings of the systems we create.

Only commit working code

Code should pass all unit tests before committing. More testing is better—if you’ve added a feature, test it end-to-end whenever practical before committing. Don’t use the repository for moving code from one machine to another.

One issue per commit

Try to restrict your work to one issue per commit whenever possible. Every commit must have an issue (even if you make the ticket at the last minute just before committing). Issue number and title should go in every commit.

Commits tracked in each issue

Cut and paste your commit logs into the issue you’re addressing. This makes it easier to find out exactly what changed in a given release or for a given issue.

Reduce technical debt when possible

See this article for definition of technical debt. Look for opportunities to clean up design weaknesses whenever possible. If you don’t have time to actually deal with the problem, file yourself (or someone else) an issue. This applies when you read someone else’s code—we watch each others’ backs.

Monthly progress reports and invoices

Please send your invoice promptly at the end of the month so I can produce the outgoing company invoice. Please give a short (1 paragraph to 1 page) summary of work done that month, along with any tickets resolved.

Communicate as briefly, respectfully, thoroughly, and thoughtfully as possible.

Not necessarily in that order.

As we work together, I would appreciate your frank feedback whenever you have some to give.

Thanks for reading, let’s do great stuff together.

John