User:Void Singer/Formating

Coding Practices: Formatting

this is a listing of how I generally format code, for readability and self documentation, not everyone likes it, but if you use something and stick with it, others will thank you, and you'll thank yourself later when you look at it and your eyes want to glaze over thinking "WTF was I doing?" You definitely don't have to format yours the same way. This is just here to share.

1. variables:
   • all user local variables are prefixed with "v" (for variable) [to quickly Id variables]
   • all variables have their type included in 3 letters (eg. vStrData) [so I know the type, saves debugging typcast problems]
   • all variables denote what they are for (eg. key vKeyOwner = llGetOwner();) [saves on comments, makes it esay to know what I'm doing]
   • all States prefixed "s" -eg sStateName [to id states]
   • all user defined functions prefixed "u" and 3 letter return type -eg uFunctionName [to Id functions and return types]
   • All Globals are prefixed with "g" [to spot globals]
   • User Functions, User States, and variables use CamelBack style (capitalized words, no spaces/underscores)
   • All Constants are prefixed "c", use all Caps, and underscores -eg cSTR_TITLE [spot non-LSL constants, avoid conflicts with new LSL constants]
   • Bitmasks and booleans are given type "vBit" and "vBoo" [to know how they are being used]
   • Vectors describing Size, Position, Degrees, or Color are given as vSiz, vPos, vDeg, & vCol, respectively
2. Braces, brackets, and parentheses:
   • Functions: space away from the container -eg. llRound( vIntNumber ); [makes it different from grouping]
   • math: always separate math -eg 2 + 2, exception increments --x, ++x [easier to read/debug, prevent unary operator errors]
   • Grouping: do not space inside, or out -eg. ((vIntNumber + 2) * 5) [makes it different from functions]
   • Events: follow function rules -eg. touch_start( integer vIntTouches ){
   • If/Loop/while: follows grouping rules with a space before group -eg if (TRUE){
   • Variables in if/loop/while tests go to the right of the comparison operator -eg if (FALSE == vBooVariable) [reduces assignment errors]
   • All control structures, states, user functions: "{" goes on the same line as the calling body, "}" after the last entry, and are ALWAYS used [readability, debugging, code insertion safety]
3. Comments: [use lots of them to remember/see what code is trying to do]
   • Sections/Headers: "//--// text //--//"
   • Code: " //-- the line below does X" (note the extra space indent)
   • Edit/Notes: " //-- the line to the left is editable or could use changes"
4. WhiteSpace:
   • blank line between event [groups event code]
   • blank line between sections of code doing different things [groups similar actions]
   • tabs are set at 2 spaces, [reduce wrapping of nested items]
   • All items inside a control structure, state, or user function are indented one level [easier to read/debug]
5. Special Items:
   • Bitmasks, Keys, and hexadecimal codes are in uppercase -eg. 0xFFFFFFFF [to see usage, readability]
   • Long tests/function calls: wrap each variable/container to the next line with level spacing -eg see below [readability, cleaner than built in wrapping]

<lsl> //--// this is an example script //--// //--// it has no real purpose other //--// //--// than to show my formatting //--//

string cSTR_TITLE = "example script:"; //-- the line to the left is a constant integer gIntTotalTouches = 0;

string uStrKey2Name( key vKeyAvatar ){

 return llKey2Name( vKeyAvatar );

}

default{

 state_entry(){
   llOwnerSay( "Hi, " + uStrKey2Name( llGetOwner() ) );
 }

 touch_start( integer vIntTouchCount ){
   do{
      //-- below is the example of wrapping functions parameters
     llSay( 0,
            cSTR_TITLE + " has been touched "           //-- this is an example of my
                       + (string)(++vIntTouchCount)     //-- function wrapping, lines start
                       + " times" );                    //-- with math/join symbols when avalable
   }while (--vIntTouchCount);
 }

 changed( integer vBitChanged ){
   if (CHANGED_OWNER & vBitChanged){ //-- variables on the right in tests
     state sReset;
   }
 }

}

state sReset{

 state_entry(){
   llSay( 0, "New Owner " + uStrKey2Name( llGetOwner() ) + " detected; resetting" );
   llResetScript();
 }

} </lsl>

Comments

Feel free to leave me a note on my User Talk page.