Cappuccino Web Framework - Coding Style Guidelines

Contribute

Cappuccino Coding Style Guidelines

Indentation

Use spaces, not tabs. Tabs should only appear in files that require them for semantic meaning, like Makefiles (which there are currently none of).

The indent size is 4 spaces.

Right:

function main() 
{
    return 0;
}

Wrong:

function main() 
{
        return 0;
}

A case label should be indented once from its switch statement. The case statement is indented out from the longest label.

Right:

switch (condition)
{
    case fooCondition:
    case barCondition:  i++;
                        break;

    default:            i--;
}

Wrong:

switch (condition) {
    case fooCondition:
    case barCondition:
        i++;
        break;
    default:
        i--;
}

Spacing

Do not place spaces around unary operators.
Right:
```
i++
```
Wrong:
```
i ++
```

Do place spaces around binary and ternary operators.

Right:

y = m * x + b;
f(a, b);
c = a | b;
return condition ? 1 : 0;

Wrong:

y=m*x+b;
f(a,b);
c = a|b;
return condition ? 1:0;

Place spaces between control statements and their parentheses.
Right:
```
if (condition)
    doIt();
```
Wrong:
```
if(condition)
    doIt();
```
Do not place spaces between a function and its parentheses, or between a parenthesis and its content.
Right:
```
f(a, b);
```
Wrong:
```
f (a, b);
f( a, b );
```
Do not place spaces between the return type of an Objective-J method and the selector name. DO place spaces between the method type and the method return type.
Right:
```
- (void)method;
```
Wrong:
```
- (void) method;
-(void)method;
```
Do not place spaces between Objective-J selectors and arguments.
Right:
```
[myNumber addNumber:5]
```
Wrong:
```
[myNumber addNumber: 5]
```

Line breaking

Each statement should get its own line.

Right:

var x,
    y;
x++;
y++;
if (condition)
    doIt();

Wrong:

var x, y;
x++; y++;
if (condition) doIt();

Braces

Every brace gets its own line, no exceptions, very simple to remember:

Right:

int main()
{
    //...
}

if (condition)
{
    //...
}
else if (condition)
{
    //...
}

@implementation MyObject : CPObject
{
}

@end

Wrong:

int main() {
    ...
}

if (condition) {
    ...
} else if (condition) {
    ...
}

@implementation MyObject : CPObject {}
@end

Null, false and 0

In JavaScript, the null object value should be written as null. In Objective-J, it should be written as nil when the variable refers to an object, and Nil when it refers to a Class. Objective-J BOOL values should be written as YES and NO.

Tests for true/false, null/non-null, and zero/non-zero should all be done without equality comparisons, except for cases when a value could be both 0 or null (or another "falsey" value). In this case, the comparison should be preceded by a comment explaining the distinction.

Right:

if (condition)
    doIt();
    
if (!ptr)
    return;

if (!count)
    return;
    
// object is an ID number, so 0 is OK, but null is not.
if (object === null)
    return;

Wrong:

if (condition == true)
    doIt();
    
if (ptr == NULL)
    return;
    
if (count == 0)
    return;
    
if (object == null)
    return;

In Objective-J, instance variables are initialized to nil automatically. Don't add explicit initializations to nil or NO in an init method.

Names

Use CamelCase. Capitalize the first letter of a class. Lower-case the first letter of a variable or function name. Fully capitalize acronyms.
Right:
```
@implementation Data : //...
@implementation HTMLDocument : //...
```
Wrong:
```
@implementation data : //...
@implementation HtmlDocument : //...
```

Multiple var declarations should be collapsed with commas.

Right:

var index = 0,
    count = 5;

Wrong:

var index = 0;
var count = 5;

Variable declarations should be created as needed, rather than up front.

Right:

- (BOOL)doSomething:(id)aFoo
{
    var importantVariable = [aFoo message];
    if (!importantVariable)
        return;
    
    var index = [aFoo count];
    while (index--)
    {
        var innerVariable = [aFoo objectAtIndex:index];
        //do something;
    }
}

Wrong:

- (BOOL)doSomething:(id)aFoo
{
    var importantVariable = [aFoo message],
        index = [aFoo count],
        innerVariable;
    
    if (!importantVariable)
        return;

    while (index--)
    {
        innerVariable = [aFoo objectAtIndex:index];
        //do something;
    }
}

Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.

Right:

var characterSize,
    length,
    tabIndex; // more canonical

Wrong:

var charSize,
    len,
    tabulationIndex; // bizarre

Prefix Objective-J instance variables with "_", but only when writing code for the Cappuccino frameworks. User level (application) code should not prefix variables with "_". This prevents conflicts between the two scopes.
Right:
```
@implementation CPString
{
    unsigned _length;
}
@end
```
Wrong:
```
@implementation CPString
{
    unsigned length;
}
@end
```

Precede boolean values with words like "is" and "did".

Right:

var isValid;
var didSendData;
- (BOOL)isEditable;
- (BOOL)didReceiveResponse;

Wrong:

var valid;
var sentData;
- (BOOL)editable;
- (BOOL)receivedResponse;

Precede setters with the word "set". Use bare words for getters. Setter and getter names should match the names of the variables being set/gotten.
Right:
```
- (void)setCount:(unsigned)aCount; // sets _count
- (unsigned)count; // returns _count
```
Wrong:
```
- (unsigned)getCount;
```
Use descriptive verbs in function names, and place desired types in comments.
Right:
```
function convertToASCII(/*String*/ aString)
```
Wrong:
```
function toASCII(str)
```

Use descriptive parameter names that are not abbreviated.

Right:

- (void)convertString:(CPString)aString toFormat:(Format)aFormat;
- (void)appendSubviews:(CPArray)subviews inOrder:(BOOL)shouldBeInOrder;

Wrong:

- (void)convertString:(CPString)str toFormat:(Format)f;
- (void)appendSubviews:(CPArray)s inOrder:(BOOL)flag;

Use descriptive parameter types, despite not being fully supported in JavaScript. At some point we will be adding optional static typing, and even until then this serves as a much better indicator of what the method expects. Of course, if the method can truly take any input or return any output, it is perfectly acceptable to use "id", "CPObject", or "var".
Right:
```
- (char)characterAtIndex:(unsigned)anIndex;
- (void)insertObject:(id)anObject;
```
Wrong:
```
- (String)characterAtIndex:(var)index;
```
Objective-J method names should follow the Cocoa naming guidelines — they should read like a phrase and each piece of the selector should start with a lowercase letter and use intercaps.
Enum members should user InterCaps with an initial capital letter.
#defined constants should use all uppercase names with words separated by underscores.

Macros that expand to function calls or other non-constant computation: these should be named like functions, and should have parentheses at the end, even if they take no arguments (with the exception of some special macros like ASSERT).

Right:

#define StopButtonTitle() \
        CPLocalizedString(@"Stop", @"Stop button title")

Wrong:

#define STOP_BUTTON_TITLE \
        CPLocalizedString(@"Stop", @"Stop button title")

#define StopButtontitle \
        CPLocalizedString(@"Stop", @"Stop button title")

import Statements

Include external frameworks first.
Include Foundation classes before AppKit classes.
Include files in alphabetical order.

Use local imports whenever possible.

Right:

// (Within AppKit)
import <Foundation/CPObject.j>
import <Foundation/CPArray.j>

import "CPTabViewItem.j"
import "CPTabView.j"

Wrong:

// (Within AppKit)
import "CPTabView.j"
import <AppKit/CPTabViewItem.j>

import <Foundation/CPArray.j>
import <Foundation/CPObject.j>

Contribute

Cappuccino Coding Style Guidelines

Indentation

Right:

Wrong:

Right:

Wrong:

Spacing

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Line breaking

Right:

Wrong:

Braces

Right:

Wrong:

Null, false and 0

Right:

Wrong:

Names

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

Right:

Wrong:

import Statements

Right:

Wrong:

Learn

Discuss

Contribute

Download