Site Menu
Extra Info Menu
Cocoa Units Logo

Cocoa Units Guidelines

Like all large projects, Cocoa Units requires certain minimal coding conventions. The benefits of these conventions are:

  • Ease of Reuse - If you don't understand it, you can't use it. Coding conventions allow us to understand each other's code as a group. It also allows us to fulfill one of the promises of this project; providing high-quality example code and explanations to the developer community at large. Only by having good documentation can we fulfill this promise.
  • Ease of Documentation - By coding the same way and by using resources like headerdoc, we can ensure that the knowledge we gain can be widely disseminated with minimal effort on the part of anyone using this site.
  • Bug Hunting - This relates to the upper two points. If we understand each other's code well, then it becomes much easier to track down bugs, both in Apple's software and in our software.

The disadvantages are few; you spend a few moments extra on each function filling out an explanation of what you are doing, and you run the headerdoc tool to make sure that you didn't accidently include any bugs.

The Conventions

Documentation Conventions

In a nutshell, apply headerdoc's tags to all of the code that you write, and you're more than halfway there. Beyond that, you have to use your own best judgement as to whether you've documented enough, and if the documentation that you've written is well written.

  • Is the documentation accurate?
  • Does it cover any known bugs?
  • Does it explain what good and bad input are?
  • Can you use this documentation to write good code?

If you were able to answer 'yes' to all of these questions, then it is likely that you've written a useful set of documentation. (As a personal measure, ask yourself if you would want to use this code if you've never seen it before)

More specifically, here is the minimal set of information that should be with each test.

  • The API that you're testing - Tell us which API or subset of APIs you're testing. For example, if your tests cover the NSData class, then tell us that.
  • Tell us what you're testing within the APIs - Each function of each API needs to be tested for both valid and invalid input (see the Bug Tests page for more info) and that means that we need to know what you are testing FOR.
  • What you've learned about the API - just as important as the bugs you're testing for is an explanation of the API and methods that you're testing do. The headers that Apple provides are well documented and well written, but they still haven't had time to convert all of that documentation to HTML. You can help by providing some of that documentation.
  • Use HeaderDoc - I am repeating myself here, but using headerdoc in an intelligent and complete way really covers most of what we need. So go get, learn it, and USE it!

Coding Conventions

The following are conventions that must be followed for the Cocoa Units project. Your code will not be accepted if you do not follow these conventions! Since the code in this project is designed for Cocoa newcomers, it is very important to stress self-documenting code and high readability. To see more examples, view the code all ready submitted to the project.

Variable Names: Variable names start with a lower-case latter. Each succeeding letter is lower-case unless it is the first letter of a new word. Names are as descriptive as possible, often sacrificing typing time for clarity.

Correct:  NSDecimalNumber *valvePressure;
NSString *lastName;
Incorrect:  NSDecimalNumber *vp
NSString *ln

Method Names: Like variable names, method names should be as descriptive as possible. Method names start with a lower-case latter. Each succeeding letter is lower-case unless it is the first letter of a new word. A method that performs an action should generally begin with a verb describing the action it performs. If the sole purpose of a method is to return a value, the name should describe the value it returns. If the method returns the value of an instance variable, the name of the method should be the same as the value it returns. For methods that take arguments, the name generally contains information regarding the arguments to the method.

Correct:  - (void)removeObjectAtIndex:(int)anIndex;
- (id)objectAtIndex:(int)index;
Incorrect:  - (int)iRemoveobj:(int)num;
- (id)obj:(int)num;

Constants: Constants that are #defined are all upper-case with underscores separating words.

Correct:  #define LENGTH_OF_CHAR_STRING 16
#define BLUE 1
Incorrect:  #define LengthOfCharString 16
#define blue 3

Classes and User-Defined Types: Classes and types that are definied by the user with typedefs begin with an upper-case letter for the beginning of each word in the name. All other characters are lower-case.

Correct:  @interface NSFileItem: NSObject;
typedef int SignedInteger;
Incorrect:  @interface nsfileitem: NSObject;
typedef int signedint

Bracing: The use of curly-braces {} follows one of two styles depending upon the case.

Case 1: K&R Style braces for method implementations.

Example:  -(void) doSomethingSpecial
{
     ...
}


Case 2: One-True Brace Style braces for everything else:

Examples:  if (someBooleanValue) {
     [object doThis];     
} else {
     [object doThisInstead];
}

do {
     [person eat];
} while ([person isHungry] == TRUE);

Remember, following these conventions are very important. Again, if you do not follow these conventions, your submissions will not be accepted! So make sure you follow these rules.

Homepage Our Goals Guidelines Getting Started Links FAQ Contact Info Cocoa Units at Sourceforge