IOS Coding Standards

[mikeh]

DevelopingCommunity

Table of Contents

• 1 Scope


• 2 iOS Coding Standard


• 3 File Formats


• 4 Deviations


• 5 Xcode


• 6 Logging


• 7 General Coding Practice


• 8 File Headers


• 9 Third Party Code

Scope

These are the standards used by the Alfresco Mobile Engineering team for development on the iOS application and SDK, and should be followed when submitting changes for inclusion into either of those projects.

These standards reflect how we want the code to be, not necessarily how it currently is.

iOS Coding Standard

• The core of our coding standards follow Apple's Coding Guidelines for Cocoa, especially around descriptive naming of methods and properties.
  
• Out-of-the-box Xcode formatting should be preserved, including using 4 space characters for tab indents.
  
• New import declarations should be added to the end of existing imports in order to reduce merge conflicts.
  
• If adopting a significant number of protocols (i.e. more than 2) consider alphabetizing and splitting onto separate lines - again to try and reduce merge conflicts.
  
• Implementation files should contain just one class except in very special cases.
  

File Formats

• Unicode (UTF-8) encoding of all text files
  
• OS X / Unix line endings (LF)
  

Deviations

• Braces are on new lines, except when declaring a completion block
  

Xcode

• Always use the latest non-beta release of Xcode
  

• Preferences -> Text Editing -> Editing
  
  • Set 'Default text encoding' to 'Unicode (UTF-8)'
    
  • Set 'Default line endings' to 'OS X / Unix (LF)'
    
  • Deselect 'Convert existing files on save'
    

• Preferences -> Text Editing -> Indentation
  
  • Set 'Prefer indent using' to 'Spaces'
    
  • Set 'Tab width' to '4' spaces
    
  • Set 'Indent width' to '4' spaces
    

Logging

• If developing with, or including the AlfrescoSDK project, the AlfrescoLog... macros should be used instead of NSLog() directly
  
• Log messages should be recorded at the appropriate level for the severity of the message. Don't use Error or Warning levels for debug or trace purposes even though it might appear to be more convenient.
  
• If log messages at Debug or Trace levels require significant calculation or string manipulation, make the code conditional on the current log level to avoid unnecessary CPU cycles.
  

General Coding Practice

This section is meant for contributors to our main code streams.  Naturally, you will be able to find violations within our own code.

• Become familiar with the existing codebase and try to maintain the same conventions for new code
  
• Whilst we won't nit-pick over missing spaces and minor code layout differences, it helps greatly during the code review and acceptance process if the reviewer isn't distracted by these minor infractions
  
• We take the view that comments should be descriptive but not simply repeat the code. If your code isn't self-documenting it probably means you haven't followed Apple's Cocoa standards. Comments should augment the code and describe the 'why' not the 'how'.
  
• Use modern Objective-C whenever possible (this is why we mandate the latest version of Xcode)
  

File Headers

At the time of writing, all Alfresco iOS code is licensed under the Apache License, Version 2.0. Any code contributions should be similarly licensed otherwise we may not be able to accept them.

• Copy the license style at the top of existing class files
  
• Author tags are optional
  

Third Party Code

• Only Apache, MIT or BSD licensed code is appropriate to include with any contributions. We will automatically reject any code licensed under the GPL or LGPL.
  
• The apprpriate license must be included with the third party code, as well as the URL or a source repository when available.
  
• We will never accept precompiled libraries from third parties without full accompanying source code and license.
  
• Other assets such as images, PDFs or Office documents should have their source clearly identified and their redistribution rights checked. We will reject any assets not traceable to their source.