Programming Style

Style is how you format your code so that it is easy to read and thus easier to understand. Good style includes the use of whitespace, comments, indentation, and naming.

Programming Style

General Thoughts on Making Code Readable

As in all writing, the use of whitespace, separators, and formatting is very important. Remember, you almost never write code just for yourself. Other people are going to read and modify your code. Try to make it as easy as possible for them.

The core of good style is well written comments, the use of whitespace, and proper indentation. Each category is talked about below:


The Art of Commenting

You should write comments in your code to allow the "next" programmer to come along and have to update/maintain your code to be able to easily and quickly grasp the high level goals and/or techniques used in your code. A good comment eliminates the need for the "user" of your code to "read" the code itself. The comment should explain the inputs, outputs, and basic workings (in English) of your code.

Comments come in two forms: Block comments and Single line comments. A block comment has a "start" and an "end" marker and everything in between is ignored by the computer. A single line comment has a "start" marker and ends at the end of the current line.

For more on comments, see the chapter on commenting.


Indentation and Alignment are Very Important

The proper use of indentation will make your code 100% more readable. It is up to you to make sure things are properly aligned.

I suggest a TAB setting of 2 characters. This gives enough space for the reader to follow your indentation scheme without unduly pushing you off the edge of the screen. Further, all "blocks" of code that are "at the same level" should match up.

Here is a sample code. It doesn't really work, but it should show you how declarations and blocks should be formatted. Notice the alignment between blocks and how variables declarations are aligned and separated to make the code clearer.

Sample Indentation and Alignment

Matlab

            
%
% Header Comments (see commenting topic)
%

function age_in_seconds = compute_age_in_seconds( age_in_years )

   % The code "inside" the function is "indented".

   age_in_seconds   = 0;
   seconds_per_year = 60 * 60 * 24 * 365;

   % here we simulate multiplication using a while loop

   while ( age_in_years > 1 )

       % The code "inside" of the while loop is indented.

       age_in_seconds = age_in_seconds + seconds_per_year;
       age_in_years = age_in_years - 1;

   end   % end the while loop (and "un-indent").

 end % function (and "un-indent")
            
          

ActionScript

            
              
/**
 * Header Comments (see commenting topic)
 */

function compute_age_in_seconds( int age_in_years ) : int
{
   // The code "inside" the function is "indented".

   var age_in_seconds   : int  =  0;  // notice alignment of variables, types, equals, and math!
   var seconds_per_year : int  =  60 * 60 * 24 * 365;

   // here we simulate multiplication using a while loop

   while ( age_in_years > 1 )
     {
       // The code "inside" of the while loop is indented.

       age_in_seconds = age_in_seconds + seconds_per_year;
       age_in_years = age_in_years - 1;

     } // curly braces "match" (and "un-indent").

} // curly braces match (and "un-indent")
            
          

C Language

            
              
/**
 * Header Comments (see commenting topic)
 */

int compute_age_in_seconds( int age_in_years )
{
   // The code "inside" the function is "indented".

   int age_in_seconds   = 0;  // notice alignment of types, variables, equals, and math!
   int seconds_per_year = 60 * 60 * 24 * 365;

   // here we simulate multiplication using a while loop

   while ( age_in_years > 1 )
     {
       // The code "inside" of the while loop is indented.

       age_in_seconds = age_in_seconds + seconds_per_year;
       age_in_years = age_in_years - 1;

     }   // curly braces "match" (and "un-indent").

} // curly braces match (and "un-indent")
            
          

Bad Style Example

Compare the nice indentation above to the poor indentation below.... Both are the same to the computer... but what about to the person who as to maintain the work...

        

        function age_in_seconds = ...
    compute_age_in_seconds( ...
       age_in_years )
           age_in_seconds   = 0;       seconds_per_year = 60 * 60 * 24 * 365;

                 while ( age_in_years > 1 )
                    age_in_seconds = age_in_seconds + seconds_per_year;
                       end
                              end 

        
      

Whitespace:

While, most programming languages, don't care how much code you put on a single line (or even how many spaces are used between words), People Care! Write your programs in such a manner that people can read them.

Which looks better?


Parentheses:

Parentheses should always be used in the following places:


The semi-colon:

The semi-colon should always be used to mark the end of certain statements. These include assignment statements and "lone" function calls.

The semi-colon should never be used to mark the end of while loops of if statements, or function declarations, or end statements.

Matlab

            
            % Correct usage:

            if ( x == 10 )
              y = 5;  <-- correct
            end


            % Incorrect usage:

            % if ( x == 10 );  <-- wrong
            %   y = 5;
            % end;  <-- wrong
            
          

ActionScript

            
            // Correct usage:

            if ( x == 10 )
              {
                y = 5;  <-- correct
              }


            // Incorrect usage:

            // if ( x == 10 );  <-- wrong
            // {; <-- wrong
            //    y = 5;
            // };  <-- wrong
            
          

Clever Sections of Code (Tricky Solutions)

Sometimes we think of a really clever way to achieve a goal. Perhaps a really cool mathematical formula, or a tricky bit of AND/ORing, or the use of assumptions which we know to be true about our data, but other people might not.

If you do something clever that is not obvious to everyone else, add a comment to briefly describe what you have done. Do not comment every line! This will only make your code unreadable to you and everyone else. If you are not doing something tricky then the code should be able to tell the story for you.


Back to Topics List