View Single Post
 
Old 06-03-2002, 04:34 PM
loquin's Avatar
loquin loquin is offline
Google Hound

Retired Moderator
* Guru *
 
Join Date: Nov 2001
Location: Arizona, USA
Posts: 12,400
Post Would you care to Comment on that???

“Well what do you know here is another darn article on coding and standards why would anyone want to bother with that just read my code and you can see what is going on and understand it easily my friend john said that he can read my code just fine so im not even going to read this one”

If you can read my little parody as easily as you could read a paragraph with spacing, capitalization, and punctuation, then you are in the minority. e. e. cummings pioneered throwing away all the capital letters, which may be fine in regards to poetry. However, he still used punctuation and spacing to help achieve dramatic impact. Our goals as programmers shouldn't include producing “dramatic' code, however…

Seriously though; what should our code look like? Everyone you talk to has a little different interpretation of good programming style, however, there are some common threads.

Indentation
Indentation can be extremely useful when trying to understand code; essentially, the code within a conditional statement (If-Then-Else or Select-Case) or inside a loop structure (For, Do) is indented, making code easier to comprehend. Consider the following two code examples, for instance:
Code:
Private Sub cmdNext_Click() On Error GoTo GoNextError ' move if not at end If Not adoPrimaryRS.EOF Then adoPrimaryRS.MoveNext If adoPrimaryRS.EOF And adoPrimaryRS.RecordCount > 0 Then Beep 'moved off the end so go back adoPrimaryRS.MoveLast End If 'show the current record mbDataChanged = False Exit Sub GoNextError: MsgBox Err.Description End Sub Private Sub cmdNext_Click() On Error GoTo GoNextError ' move if not at end If Not adoPrimaryRS.EOF Then adoPrimaryRS.MoveNext If adoPrimaryRS.EOF And adoPrimaryRS.RecordCount > 0 Then Beep 'moved off the end so go back adoPrimaryRS.MoveLast End If 'show the current record mbDataChanged = False Exit Sub GoNextError: MsgBox Err.Description End Sub
Because of the indenting levels in the first example, it is much easier to read than the second. Microsoft has actually performed some studies of indenting, and reported that indent levels of 3 or 4 characters were the easiest to read and comprehend.

FYI, An outstanding free VB Add-on is available at VBCity.com: it's called PrettyCode.Print. When printing, this add-on will indent and format your code (for the printout only - it won't touch the source,) add page headers/footers, and add begin-end connection lines, which can really benefit you when trying uncover logic errors in your code.

White Space
White space is just what it sounds like - additional spacing between lines of code. It's certainly not needed for the program to run properly, and it will take extra space on your screen, causing you to scroll more than you otherwise would. The basic idea is that separate concepts should be separated by an extra line or two. When comparing writing code to writing a story, think about how a book is laid out. It has sentences, paragraphs, and chapters. Your program will (or should) have the same sort of structure. Functions and Procedures will correlate to chapters; Statements should correspond to sentences. In your code, if a portion of the code has a common thread; perhaps you are setting printer font properties, for instance, you should add an extra, blank line before and after this code. Someone else who is looking at your code can easily see that all the code in this 'paragraph' deals with a common concept. It helps in the visualization and comprehension of your program.

Let's look at the same piece of code as before, both with and without the white space.
Code:
Private Sub cmdNext_Click() On Error GoTo GoNextError ' ' move if not at end If Not adoPrimaryRS.EOF Then adoPrimaryRS.MoveNext ' If adoPrimaryRS.EOF And adoPrimaryRS.RecordCount > 0 Then Beep 'moved off the end so go back adoPrimaryRS.MoveLast End If ' 'show the current record mbDataChanged = False ' Exit Sub ' GoNextError: MsgBox Err.Description ' End Sub Private Sub cmdNext_Click() On Error GoTo GoNextError ' move if not at end If Not adoPrimaryRS.EOF Then adoPrimaryRS.MoveNext If adoPrimaryRS.EOF And adoPrimaryRS.RecordCount > 0 Then Beep 'moved off the end so go back adoPrimaryRS.MoveLast End If 'show the current record mbDataChanged = False Exit Sub GoNextError: MsgBox Err.Description End Sub
It's amazing how much easier it is to read code that has sufficient white space in it to separate the concepts.

Comments
Comments are an absolutely essential part of every program. When reading a textbook in college, I usually would highlight the key concepts in the text with a neon highlighter, and jot notes in the margins. Most college textbooks are laid out with extra-wide margins for this very purpose. In fact, at Half.com, an ebay sponsored used book website, I noticed that textbooks with “heavily commented margins” were selling for more than the “Like New” versions of the same book. What about that! Comments really ARE worth something!

The programming concept is the same. In your programs, the key concepts should have a comment that explains what you are doing, and sometimes, if the concept is abstract or obscure, why you are doing it. It is certainly possible to overdo commenting, and to insert way too many of them. However, this is usually not a problem. If in doubt, ask yourself if a new programmer in your department would benefit from a comment in this location. (Or if you are the new programmer, ask yourself “Would it benefit me to have this here when I have to look at this code again in 6 months?” )

Commenting is the one major area that, as we gain experience and skill in our profession, we actually tend to get worse at doing. “There's nothing new in THIS code, I don't need a comment here…” you may say to yourself. Well, as I said earlier, try to put yourself in the position of someone fresh out of college. Would a few words in a comment help explain what you're doing?

I once knew a programmer who had written a large, elaborate COBOL program for our accounting department. This person had created an application that worked wonderfully well. However, the code was poorly commented, and very complex. He had essentially created great job security for himself. There was, however, one drawback. Because the code was so complex and difficult to understand, the author could never be promoted! He ended up being pigeon-holed into his current position. Then, when the old mainframe was retired in favor of a new, Oracle-based accounting system, he was laid off...


Associated with all three concepts that I've discussed in this article, is the multi-statement line. In order to interactively run multiple statements at once in the debug window, Microsoft included the ability to enter multiple statements on one line, separated by the colon ( “:” ) An example of this might be a loop to print all the values in an array :
Code:
Dim L: For L = 0 to Ubound(intArray)-1: Debug.Print L, intArray(L): Next
This type of code, while it could be used in an application, violates all three common style guidelines at once! It's not indented, it has zero white space, and has no comments. Unless there is an awfully good over-riding reason to program in this style, don't, repeat, don't do it.

The last common style point that I wanted to discuss concerns the length of a sub or function. Under normal conditions, you should try to limit the total length of a sub to a screen or two in length. By breaking up long sections of code into smaller subs or functions, not only do you make the individual portions of code easier to understand, you act to modularize your code. Once you have a module working properly, you shouldn't have to revisit it. This should tend to make you code more robust, and more easily maintained. Obviously, there will be some instances where you choose to have a sub be longer than the recommended length. This could be especially true in the case of a custom report, where you may be printing many field values. However, even in these instances, it is often possible to greatly reduce the size of your code by judicious use of loop structures and arrays.

Remember, one of your main goals as a programmer is not only to generate code that works, but to generate code that is maintainable - and this means code that is easily read and comprehended by the average programmer. The easiest way to ensure this is to make sure that your code is consistently indented, that it has enough white space to isolate the ideas and concepts, and that it is well commented.
__________________
Lou
"I have my standards. They may be low, but I have them!" ~ Bette Middler
"It's a book about a Spanish guy called Manual. You should read it." ~ Dilbert
"To understand recursion, you must first understand recursion." ~ unknown

Last edited by loquin; 05-26-2005 at 12:26 PM.
Reply With Quote