• Nano
• Home
• Licence
• Mailing List
• Screenshots
• Version History
• Getting Started
• Quick Start
• Building Nano
• Getting the Code
• Contributing Code
• Reporting Bugs
• Nano Features
• High Performance
• Nano Features
• Nano Views
• Nano Resources
• Custom Cursors
• Custom Menu Items
• Building Applications
• Building Applications
• Adding Documents
• Adding Preferences
• Adding One-Line Undo
• Adding Software Update
• Using Controllers
• Using Carbon Events
• Using HIViews
• Using Functors
• Reference Guide
• Utility Code
• Class Overview
• Coding Standards

Coding Standards

This document describes some common coding conventions and policy decisions used when creating Nano.

If you find some code within Nano that does not appear to follow these rules, please let me know!

Assertions

Nano relies heavily on assertions to detect errors, and every function will ideally assert something about each of its parameters or any preconditions.

Assertions are also used within functions to identify problems as they occur, and may be used to validate the result (although typically results would be validated by the caller).

Warnings

Nano must always compile without warnings, and compiler warnings should be treated as bugs.

Nano is built with -Wall and -Wextra, as well as several additional flags to catch warnings not covered by these flags.

Pointer Ownership

Nano follows the "Get/Create" naming convention used by CoreFoundation.

GetXXX methods either return by value, or return a const pointer/reference to data that the caller may access (subject to the owner's lifetime) but does not own.

CreateXXX methods will create a new instance of an object, or allocate new data. In either case, the caller takes ownership of the result and must dispose of it as necessary.

SetXXX methods typically take parameters by value or perform a deep copy of any pointer/reference parameters, allowing the caller to assume the parameter was retained or copied.

Nano does not currently use smart pointers, although these may be used in the future.

Deep Copies

Whenever possible, Nano objects perform a deep copy when assigning values.

This approach helps simplify memory ownership, since objects can be passed around via assignment as if they were built-in scalar types such as ints or floats.

NCFObject provides copy-on-write behaviour for all mutable CoreFoundation objects, performing copies by acquiring a reference until a mutable instance is required.

Error Handling

Errors within Nano are typically returned to the caller to handle. If no error result would be useful (e.g., setting the title of a window), a method may consume the error rather than force callers to handle failure.

Errors returned by system APIs are either used to handle failure, or asserted on with NN_ASSERT_NOERR.

Even if an error is returned to the caller, methods will frequently assert on noErr if an error would be unusual. Although the error would typically then be handled, this approach helps identify problems at the point of failure.

The Nano library does not use exceptions, and will always return errors to the caller rather than throwing an exception.

Unit Tests

Nano does not currently use unit tests for validation, although this may be explored in the future.

If you would like to propose a suitable test suite for Nano then please let me know.

Radar Bugs

All workarounds for OS bugs are commented with the appropriate Radar bug entry.