Site Map

Home
About Rapid-Q
News Archive
Download Rapid-Q
Screen Shots
View Documentation
FAQs
Compatibility Issues
Knowledge Base
Links
Code Contributions
Coding Etiquette
EZBoard Public Forum
Rapid-Q Mailing List



Contact Me

E-mail:


  Coding Etiquette

Some would argue that programming is an art, and so whatever technique works for the programmer should be fine. However, most don't feel that way, and so they decided to "enforce" some etiquette in programming. Obviously no one is going to force you to adopt one style over another, so it's up to you to decide. If you find these techniques to be helpful, by all means adopt it. The following techniques aren't standard, I don't believe there really is a standard (especially for the BASIC language), so feel free to adopt a convention that best suits you.


  Program Structure

The BASIC language does not enforce a strict program structure that other languages like C or Pascal do. However, this does not mean you should go wild and declare variables in the middle of your FOR loop, or place an $INCLUDE directive somewhere in the middle of your program either. For matters of etiquette, here's a standard programming structure that you may want to adopt:
    Directives       ie. $INCLUDE "RAPIDQ.INC"
    Declarations     ie. CONST, TYPEs, DECLAREs, MACROs
    Global variables ie. DIM, CREATE, etc...
    Subroutines      ie. SUBs, FUNCTIONs
    Main program
The order of Main Program and Subroutines doesn't really matter, choose what best suits you, but try not to alternate the two, be consistent.


  Naming Conventions

Rapid-Q is not case sensitive, so you can define a variable named MYNAME and be able to change the case of the letters, for example MyName. For matters of etiquette, be consistent, so if you capitalize MYNAME then be sure you do that for all occurrences of MYNAME. It's also a good idea, if you choose to capitalize your variable names, that all your variables are capitalized as well. For example:
    DIM MYNAME AS STRING
    DIM MYPHONE AS LONG
    DIM myAddr AS STRING*25
The last declaration is inconsistent with the previous two, so either change the above two declarations or capitalize myAddr. A popular naming convention is to capitalize all CONST variables and keywords, while normal variables and subroutines should be lowercased. As for UDTs, the first (and sometimes the second) letter should be capitalized, while the rest is lowercased. Here's an example to demonstrate:
    CONST FALSE = 0
    CONST TRUE = NOT FALSE

    TYPE TAddress
        name    AS STRING*35
        address AS STRING*255
    END TYPE

    DIM addressBook AS TAddress
    DIM myPhone     AS LONG
    DIM myName      AS STRING
    DIM dog         AS SHORT

    SUB mySub (x AS LONG)
    END SUB
You may notice that the letter T is prepended to our new UDT (TAddress). This is just a popular coding convention, T represents a Type. Of course, you can adopt any naming style you choose but, again, be consistent.


  Grouping Constants

There are times when grouping constants can help readability, especially if you maintain a lot of constants in your program. For example:
    CONST SPACE = 1
    CONST DIAMOND = 2
    CONST HEART = 4
    CONST CLUB = 8
Naturally these four constants belong to some set of cards. What you can do to help readability is to group them by changing their names slightly:
    CONST CRD_SPACE = 1
    CONST CRD_DIAMOND = 2
    CONST CRD_HEART = 4
    CONST CRD_CLUB = 8
If you have a lot of constants in your program, this can help reduce the headache involved in deciphering whether it's a constant or some method/variable you may have declared before. Grouping constants is mainly used to increase readability, especially if someone else will be looking at it. However you want to group constant names is up to you, you can append or prepend the constants with a consistent identifier. In the above example, I chose to prepend a CRD_ identifier, representing a set of cards.


  Indentation

There's not much to be said about indentation, just two words, be consistent. Some prefer to indent with 4 spaces, while others prefer 2, 3, or 5+ spaces. Indentation naturally occurs in a block statement, without indentation your code may become very hard to read, for example:
    FOR i = 1 TO 10
    FOR j = 3 TO -90 STEP -3
    NEXT
    IF s$ = "what" THEN
    IF i = 3 THEN
    END IF
    ELSE
    PRINT "s <> what"
    END IF
    NEXT
As you may notice, if you added more and more embedded block statements, your code could win the obfuscated programming contest. Perhaps that's not what you're striving for, so try to use indentation to clarify your code:
    FOR i = 1 TO 10
        FOR j = 3 TO -90 STEP -3
        NEXT
        IF s$ = "what" THEN
            IF i = 3 THEN
            END IF
        ELSE
            PRINT "s <> what"
        END IF
    NEXT
Hopefully you can see the benefits of proper indentation, however many spaces you choose to indent is up to you, it varies between programmers. Again, be consistent.


  Line Numbers and Labels

Most BASIC languages these days don't require line numbers or labels. In fact, the only reason Rapid-Q supports these is to maintain compatibility with older BASIC code. Such code can usually be run in Rapid-Q with little to no modifications. Most people have blamed GOTOs and GOSUBs for all the "spaghetti code" you see for BASIC. Trying to follow the execution of GOTOs can be rather difficult especially if you use a lot of them. For matters of etiquette, please avoid using GOTOs and GOSUBs, there's always a better alternative.


  Declaring Variables

Rapid-Q, like most BASIC languages, doesn't force you to declare your variables before you use them, but it is good practise to declare them anyway. This helps to avoid ambiguity and typographical errors. It's very easy to misspell a word, especially if you frantically code like I do. This is definitely not a requirement, but for good practise you should always turn typecheck on. It may seem like a hassle, but this can save you hours of debugging woes.






This page maintained by William Yu ©1999-2000