Software Coding Conventions

h1. Coding conventions and natural language

h2. Java and android: http://www.oracle.com/technetwork/java/codeconvtoc-136057.html

Code Examples 11.1 Java Source File Example

The following example shows how to format a Java source file containing a single public class. Interfaces are formatted similarly. For more information, see "Class and Interface Declarations" on page 4 and "Documentation Comments" on page 9

/*
 * @(#)Blah.java        1.82 99/03/18
 *
 * Copyright (c) 1994-1999 Sun Microsystems, Inc.
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 */


package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 *  
        
Class description goes here.
 *
 * @version      
        
1.82 18 Mar 1999
 * @author          
        
Firstname Lastname
 */
public class Blah extends SomeClass {
  
        
   /* A class implementation comment can go here. */

    /**  
        
classVar1 documentation comment */
    public static int classVar1;

    /** 
  
        
    *  
        
classVar2 documentation comment that happens to be
     *  
        
more than one line long
     */
    private static Object classVar2;

    /**  
        
instanceVar1 documentation comment */
    public Object instanceVar1;

    /**  
        
instanceVar2 documentation comment */
    protected int instanceVar2;

    /**  
        
instanceVar3 documentation comment */
    private Object[] instanceVar3;

    /** 
     * ...
        
constructor Blah documentation comment...
     */
    public Blah() {
  
        
      // ...implementation goes here...
    }

    /**
     * ...
        
method doSomething documentation comment...
     */
    public void doSomething() {
  
        
       // ...implementation goes here... 
    }

    /**
     * ...method doSomethingElse  
        
documentation comment...
     * @param someParam  
        
description
     */
    public void doSomethingElse(Object someParam) {
  
        
       // ...implementation goes here... 
    }
}

h2. Objective-C: http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html

The articles contained in this topic fall into two general types. The first and larger group presents naming conventions for programmatic interfaces. These are the same conventions (with some minor exceptions) that Apple uses for its own Cocoa frameworks. These articles on naming conventions include the following:

“Code Naming Basics”

“Naming Methods”

“Naming Functions”

“Naming Instance Variables and Data Types”

“Acceptable Abbreviations and Acronyms”

The second group (currently with a membership of one) discusses aspects of framework programming:

“Tips and Techniques for Framework Developers”

Developers of frameworks have to be more careful than other developers in how they write their code. Many client applications could link in their framework and, because of this wide exposure, any deficiencies in the framework might be magnified throughout a system. The following items discuss programming techniques you can adopt to ensure the efficiency and integrity of your framework.

Note: Some of these techniques are not limited to frameworks. You can productively apply them in application development.

Initialization

The following suggestions and recommendations cover framework initialization. Class Initialization

The initialize class method gives you a place to have some code executed once, lazily, before any other method of the class is invoked. It is typically used to set the version numbers of classes (see “Versioning and Compatibility”).

The runtime sends initialize to each class in an inheritance chain, even if it hasn’t implemented it; thus it might invoke a class’s initialize method more than once (if, for example, a subclass hasn’t implemented it). Typically you only want the initialization code to be executed only once. One way to ensure this happens is to perform the following check:

if (self == [NSFoo class]) {

// the initializing code

}

You should never invoke the initialize method explicitly. If you need to trigger the initialization, invoke some harmless method, for example:

[NSImage self];

Designated Initializers

A designated initializer is an init method of a class that invokes an init method of the superclass. (Other initializers invoke the init methods defined by the class.) Every public class should have one or more designated initializers. As examples of designated initializers there is NSView’s initWithFrame: and NSResponder’s init method. Where init methods are not meant to be overridden, as is the case with NSString and other abstract classes fronting class clusters, the subclass is expected to implement its own.

Designated initializers should be clearly identified because this information is important to those who want to subclass your class. A subclass can just override the designated initializer and all other initializers will work as designed.

When you implement a class of a framework, you often have to implement its archiving methods as well: initWithCoder: and encodeWithCoder:. Be careful not to do things in the initialization code path that doesn’t happen when the object is unarchived. A good way to achieve this is to call a common routine from your designated initializers and initWithCoder: (which is a designated initializer itself) if your class implements archiving. Error Detection During Initialization

A well-designed initialization method should complete the following steps to ensure the proper detection and propagation of errors:

Reassign self by invoking super's init method.

Check the returned value for nil, which indicates that some error occurred in the superclass initialization.

If an error occurs while initializing the current class, free the object and return nil. 

Natural language: English