Coding Style

If you're going to add or modify source code in TouchDB, please read and follow these guidelines. Thanks!

Source Files

• Apache license at top of all .m files (or other files containing actual code). Update the year if necessary.
• Indents are 4 spaces wide and use spaces, not tabs.
• Name category files like this: TDClassName+CategoryName.m.
• In headers, use @class or @protocol forward declarations when possible instead of #import-ing the class's header.

Preferred:

• Try to limit lines to 100 characters wide.
• Try to keep source files short. Under 500 lines is best; don't go over 1000 if you can help it. If a class gets bigger, consider breaking it up into topical categories, as was done with TDDatabase.

General Style

In general, go with Apple's style. However, we have idiosyncracies:

• I prefer to put spaces after the ":"s in messages-sends: [foo bar: 1 baz: 0]

• And I prefer to space method declarations like this, i.e. also with spaces after the colons:

    - (void) bar: (int)bar baz: (BOOL)baz;
  

• The opening curly-brace of a method/function should go at the end of the declaration line (not on a separate line), unless the declaration is multi-line.

• I actually like not putting braces around single-line if blocks. You can use braces if you want, just don't go on a "cleanup" jihad and "fix" all the existing ones.

• Use of modern Objective-C syntax is preferred, including the new shorthand for object literals and collection indexing.

The following are mandatory, though:

• You must declare instance variables in the @interface or the Mac build will fail. (It still supports the old 32-bit Mac Obj-C runtime.)
• Private methods should not be declared in the @interface.
• Internal methods (those not part of a class's API but needed by another source file, such as a category) should be declared in a category in TDInternal.h, not in the public @interface.

Name Prefixes

• Classes: TD
• Instance variables: _
• Category methods on external classes: td_
• Constants: kTD (do not use ALL_CAPS)
• Static variables: s (even if defined inside a function/method!)
• Static functions: No prefix, just lowercase.

Platform/Runtime Assumptions

• Minimum OS versions are iOS 5.0, Mac OS X 10.7.
• Minimum Xcode version is 4.5 (as of this writing.)
• The Mac targets still support 32-bit, but this may be removed (which would enable us to use new-runtime conveniences like declaring instance variables in .m files.)
• Not using ARC yet, except for the 3rd party CocoaHTTPServer code in the listener. But it would be nice to switch over to ARC if someone wants to take the time to do the conversion and testing.

Testing and Testability

• Adding unit tests is encouraged! Unlike other test frameworks, the MYUtilities one lets you put unit tests (TestCase(Foo){ ... }) in any source file. For simple tests, you can put them at the end of the source file containing the code you're testing. Larger test suites should go into their own source file, whose name should end with _Tests.m.
• If you need to create classes or static functions for use by unit tests, make sure to wrap them and the tests in #if DEBUG, so they don't take up space in a release build.
• Use Assert() and CAssert() fairly liberally in your code, especially for checking parameters.
• Use Warn() wherever something happens that seems wrong but shouldn't trigger a failure.

Pre-Commit Smoke-Check:

• Build both the Mac and iOS demo app targets, to catch platform- or architecture-specific code.
• Run the static analyzer (Cmd-Shift-B). There should be no issues with our code (there may be one or two with third-party code.)
• Run the unit tests on both platforms: run the demo app with custom arguments Test_All and Test_Only. (This is really easy to do using Cmd-Opt-R.) All the tests must pass.
• Before committing, review your patch hunk-by-hunk to make sure you're not checking in unintended changes.
• Are you fixing an issue filed in Github? If so, put something like Fixes #999 in the commit message, and Github will automatically close the issue and add a comment linking to your commit.