Thinking in programming

Things I like to talk about programming

General Coding Conventions

leave a comment »

Rules

1 Self explanatory code. Make sure your method, class, instance, param and all other self written names in your code are self explanatory.
2 Always include explanatory comments in the code. Make sure every class and method has comments explaining what it does and its purpose, this will make the API documentation easier to understand for other without diving into the code.

/**

  • Get a random prime number starting to search it from a minimal number (default 1)
  • @param minNumber Number Optional minimal number where start the search. Default to 1
  • @return Number Random prime number
  • /

public function findRandomPrimeNumber(minNumber:Number = 1):Number {

}

3 Follow the DRY (Don’t repeat yourself) code philosophy. Make helpers. Make modules. Make plugins. Think in reusable components.

  • If you have a common functionality for two or more classes, please consider to include such functionality in a helper class.
  • If you made a class which have only static functions, like in the case of Utility or Helpers Classes, please consider to use the Singleton Pattern.
4 Avoid too long functions (more than 200 lines). Split to smaller internal functions as needed.

/**

  • /

public function myLongFunction():void {

// Wash clothes
washClothers();

// Now dry them up
dryCycle();

// Notify master that laundry is done
notifyMaster();
}

5 Avoid empty catch blocks. When the exception occurs, nothing happens, and the program fails for unknown reasons.

In general, when a exception occurs, it can be thrown up to the caller, or it can be caught in a catch block. When catching an exception, some options include: inform the user (strongly recommended), log the problem, send an email escribing the problem to an administrator. Deciding what exactly to do seems to depend on the nature of the problem. If there is an actual bug in the program – a defect that needs to be fixed – then one might do all three of the above. In this case, the end user should likely be shown a generic “Sorry, we goofed” message, not a stack trace. It is usually considered bad form to display a stack trace to a non-technical end user, or if exposing a stack trace may be a security risk. If the exception does not represent a bug, then different behavior may be appropriate.
6 Always include { and } on the statements, even if there is a single block code line.
7 Be sure of read all the coding conventions on: Coding Guidelines

Recommendations

1 Only one return on a same function. Do not use returns to break the flow of the code.

  • If you want to know where something is returned, you have to look for the return statement. With multiple return statements you have to go read the complete method and find all the exit points of a method. (isn‘t your method too big?)
  • If you want to log before you exit a method, so with multiple return statements you need to place that logging code before all return statements.
Advertisements

Written by roger.padilla

February 15, 2009 at 15:10

Posted in Coding Conventions

Tagged with

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: