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.
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:
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.
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.
%
% 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")
/**
* 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")
/**
* 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")
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
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?
Judicioususeofwhitespacecanmakeaprogrammucheasiertoread.
Judicious use of whitespace can make a program much easier to read.
Parentheses should always be used in the following places:
While loops: Around the conditional test
while ( money < 100 )
% Incorrect usage (no parens):
%
% while money < 100
If statements: Around the conditional test
if ( money < 100 )
% Incorrect usage (no parens):
%
% if money < 100
Function calls: Around the arguments (even with zero values)
function( );
doit();
answer = get_answer();
% Incorrect usage (no parens)... this looks like two variables!
% answer = get_answer;
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.
% Correct usage:
if ( x == 10 )
y = 5; <-- correct
end
% Incorrect usage:
% if ( x == 10 ); <-- wrong
% y = 5;
% end; <-- wrong
// Correct usage:
if ( x == 10 )
{
y = 5; <-- correct
}
// Incorrect usage:
// if ( x == 10 ); <-- wrong
// {; <-- wrong
// y = 5;
// }; <-- wrong
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.