You should format your source code so that it is readable and understandable. This will aid in debugging and maintenance of your programs.
There are many programming styles and you should adopt one that you feel comfortable with.
Structure
A well structured program is a must if it is to be readable or understandable by other people. A few guidelines in this regard are:
· Use an Object-Oriented approach when developing a program for a complex problem. View the problem in terms of objects (e.g. Lisa, bed) and operations (e.g. sleep, wake up), then produce a program that takes these operations (represented by subroutines) and applies them to the objects (represented by classes, variables, etc.)
· Create whitespace. A program should be aethestically pleasing; it should be formatted in a style that enhances its readability. A few suggestions are:
· Use spaces between items in a statement. For example, use spaces before and after each operator (+, &&, ==, etc.)
· Insert a blank line between sections of a program to set off blocks of statements.
· Maintain strict indentation of statements to emphasize the relationships between different sections of a program. Nested loops are notoriously difficult to understand without proper indentation.
Documentation
A program should be well documented. A few guidelines follow:
Two types of documentation exists: external and internal. External documentation, generally, is in the form of manuals and reference guides (aimed towards the end-user) that explain how to use the program. Internal documentation, on the other hand, is usually in the form of comments in the source code and is more focussed in explaining how the program works to the programmer.
· Program description. At the minimum, there should be a comment box at the beginning of each program describing what the program does, assumptions, revisions (along with their dates), and other useful information. Similar descriptions beside each function can also be helpful.
· Describe complex algorithms and key program segments.
· Do not over-document. Too many detailed or unnecessary comments clutter the program and make it more difficult to read and understand.
· Use meaningful names. Variable and sub-routine names should be representative of their role within the program. For example:
Hypoteneuse = SquareRoot( Square(OppSide) + Square(AdjSide) );
and
c = SR( SQ(a) + SQ(b) );
the above code segments are equivalent, but the former is definitely more descriptive of its operations.