aljungberg/test.md

## test.md

      
    Raw
  

              test.md
            
          
    Contributing

As an open source project, your contributions are important to the future of Cappuccino. Whether you're looking to write code, add new documentation, or just report a bug, you'll be helping everyone who uses Cappuccino in the future.
Reporting Bugs

We use GitHub to track issues. You might be interested in our issue life cycle which explains the process of how an issue is taken from new to resolved.
Patches

To contribute a patch or a fix, fork Cappuccino and then clone your fork and make the changes to a branch of your fork:
git clone https://github.com/<your username>/cappuccino.git
git checkout -b descriptive-branch-name master

# Check that the unit tests work.
jake test

# Make changes. Make sure you follow the coding style guidelines and write unit tests.

# Check that everything is still working, then commit.
jake test
git commit

git push origin descriptive-branch-name

Now you can go to GitHub and make a pull request.
Some things are difficult to unit test in a way that's worthwhile. For instance a change to the mouse interaction of a CPButton. In this case a manual test is fine instead. Find the closest related manual test in Tests/Manual and add whatever it takes to easily reproduce the patched behavior, ideally with some labels describing how someone running the manual test should exercise it.
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, 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 ("hoisted").
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>