Welcome to the Second Life Forums Archive

These forums are CLOSED. Please visit the new forums HERE

Coding Standards RFC

Arpie Perkins
Junior Member
Join date: 21 Jul 2003
Posts: 7
08-31-2003 13:41
Hi guys,

I'm fairly new in LSL, still doing baby steps, however I'm also a fairly seasoned programmer.

I think we have a great opportunity here to make sure people write good scripts. All we have to do is define what a good LSL script is.

Here are some suggestions:
- Globals should have a naming convention. i vote for ALL_CAPS.
- Functions and variables should be aptly named, even if it means a longer name. For example, if you have a list with simulator names, it should be called "simulatorNames", not "sl"; if you have a function to set a texture on one of the object's faces, it should be called "setOneFaceTexture" not "function1". This is valid for function parameters as well. For example if your "on_rez(integer start_param)" passes a parameter that will have a weapon damage setting, call it "on_rez(integer damageSetting)". Good names make the code self-documenting in many instances.
- Functions should be small, if possible fit in one page -- this helps readability and makes the code easier to understand.
- Comments are good. They should be helpful but concise. They should be either above the line you're explaining or on the same line. You don't need to explain about syntax, unless you're writing a tutorial saying "// i++ is the same as i = i + 1" just clutters the script.

These are just some things that pop into my mind, I'm sure people, especially the ones that are more familiar with LSL that me, will have great ideas. When we have enough, we can write a coding standards guidelines document, which I'm sure will help people understand each other's code better and share more code. Trust me, this is from someone who has to work with other people's code... :-p
_____________________
/* TAANSTAFL */
Nada Epoch
The Librarian
Join date: 4 Nov 2002
Posts: 1,423
08-31-2003 17:05
Things that I always think about and rarely do a.k.a. other good coding tips :D
_____________________
i've got nothing. ;)
Arpie Perkins
Junior Member
Join date: 21 Jul 2003
Posts: 7
Compiling a document
08-31-2003 19:34
Thanks Nada.

Some information on that thread is very good, some of it i don't particularly agree with.

I think we could use this current thread to iron it out, then compile a guidelines document. What do you think?

Some examples/ comments:
- optimization/ preventing lag features (disable silly or unseen scripts, minimizing the number of objects, however I don't love the idea of adding "return" calls all over, call me purist but stuff should just be in conditional blocks);
- best debugging techniques;
- more on naming conventions, including the types, etc. (yuck... I'm a spoiled Perl programmers, I *dont like* strong typed variables ;-);
- where to put curly brackets ("{" -- or always on their own line and the start and end lining up);
- i,j,k for loops;
- I particularly don't like the suggestion of using "======..." line separators on comments... i think they just add visual clutter, especially if you have a syntax highliter that changes the line colors, also adding a comment to say "function X ends here" is also visual clutter when your brackets line up nicely and your functions are small.

Of course, this is all IMHO. I suggest we all discuss this and then come up with nice clean guidelines.
_____________________
/* TAANSTAFL */
Nada Epoch
The Librarian
Join date: 4 Nov 2002
Posts: 1,423
08-31-2003 19:57
I don't think of these so much as guidelines, as suggestions. And I am all for compiling large listes of suggestions. If people post their suggestions to this thread, I will compile it into one large readable document, kind of as a suggestion to noobs, and novice coders. So post away :D.

If the post doesn't show up right away, it means that i haven't made it to the moderators board yet. Give me one to two days, and if you don't see it by then, shoot me a pm
_____________________
i've got nothing. ;)
Arpie Perkins
Junior Member
Join date: 21 Jul 2003
Posts: 7
08-31-2003 20:10
From: someone
Originally posted by Nada Epoch
I will compile it into one large readable document, kind of as a suggestion to noobs, and novice coders.

I think this should be for everyone, even more experienced programmers who may have not so good habits.

Old dogs can learn new tricks too. Hey, the tricks might turn out even better than the old ones. ;-)
_____________________
/* TAANSTAFL */
Huns Valen
Don't PM me here.
Join date: 3 May 2003
Posts: 2,749
09-02-2003 22:08
This is my coding style.

CODE

// Comments and lines are split at the width of a notecard
// in order to avoid ugly line wrapping

// Constants uppercase
integer GLOBAL_CONSTANT;

// Globals use camel-caps, optionally with a leading "g"
string globalVariable;
string gGlobalVariable;

// Now the global functions
// Curly braces always on same line as relevant scope entity
string whap(vector v) {
// Do stuff
}

integer slap(key id) {
// Do stuff
}

// Now the default state
default {
state_entry() {
// All variables defined at top of function.
// Local variables use camel-caps.
// API calls that need to be read more than once
// but won't change between reads are called only
// once and assigned to a var.
// Operators always have a space on either side.
vector startPos = llGetPos();
key owner = llGetOwner();
integer x;

// Different units within a function should have
// an empty line between them. Each unit should
// have a comment at the top to explain what it
// does.
llMoveToTarget(startPos, .1);
for(x=0; x<25; x++) {
llWhisper(0, (string)x);
}

// Lines that would be incredibly long and ugly are
// chopped and indented instead of being allowed to
// wrap. We are also adding an empty line because
// we are doing something new, because it is
// aesthetically pleasing, or because there is a
// comment block.
llSetStatus(
STATUS_PHYSICS |
STATUS_ROTATE_X |
STATUS_ROTATE_Y |
STATUS_ROTATE_Z,
TRUE);

// Or like this.
llSetStatus(
STATUS_PHYSICS | STATUS_ROTATE_X |
STATUS_ROTATE_Y | STATUS_ROTATE_Z,
TRUE);

// Don't comment this: it is totally obvious what it
// will do. Good code is largely self-documenting!
// Note that I did not whitespace the (string) cast.
llInstantMessage(owner, (string)startPos);
}

// Empty line between events
sensor(integer num_detected) {
// Do stuff
}
}


// States are separated by two empty lines.
// Heavy sensor(), timer(), etc. callbacks can be split between
// states in order to avoid having a mile-long callback,
// particularly if the device has different modes of operation
state other_thing {
default_entry() {
// Start sensor
llSensorRepeat(blah blah blah blah blah);
}

// Empty line between events
sensor(integer num_detected) {
// Do stuff
}
}
Nada Epoch
The Librarian
Join date: 4 Nov 2002
Posts: 1,423
09-03-2003 10:32
From: someone
From the original Email requesting scripts
The secondary goal is to try and make the most common scripts be very simulator efficient so that everyone who want so make spinning cubes or scrolling textures won't use bad scripts.

This thread will be about both stylistic issues, and good coding practices, both of which seem to me to be part of the original intent of this section.


And to show what i mean by good coding practice, here is a simple script for a toggle switch.

CODE

integer swtich = -1;

default
{
touch_start(integer a)
{
switch *= -1;
if(switch >0)
{
//do one thing, like say turn on.
}
else
{
//do something else, like say turn off.
}
}
}
_____________________
i've got nothing. ;)
Jake Cellardoor
CHM builder
Join date: 27 Mar 2003
Posts: 528
09-03-2003 13:31
I was thinking about adding an example just like Nada's to the help file, to help explain states to novices. Nada's example demonstrates a toggle without using states. The equivalent example using states looks like this:

CODE

default
{
touch_start(integer total)
{
state running;
}
}

state running
{
state_entry()
{
// start doing stuff
}

touch_start(integer total)
{
state default;
}

state_exit()
{
// stop doing stuff
}
}


Okay, now a question about coding practices: what are the reasons to prefer one over the other? When are states desirable and when are they not?

I'm not aware of any difference in performance, so barring that, I'd recommend states whenever it's conceptually useful. In the example above, the running state helps group together the object's behavior when it's "on" as opposed to "off"; this is easier than checking the value of the switch variable in every event handler.
Christopher Omega
Oxymoron
Join date: 28 Mar 2003
Posts: 1,828
09-03-2003 15:26
I like my code better :D :

CODE

integer gSwitchOn = FALSE; //boolean, tells if switch is on or not.

default
{
touch_start(integer totaltouches)
{
if(gSwitchOn) //if the switch is on
{
}
else //the switch is off
{
}
gSwitchOn = ~gSwitchOn //switches the bits of gSwitchOn, if it was TRUE, makes it FALSE, if it was FALSE make it true.
}
}
_____________________
October 3rd is the Day Against DRM (Digital Restrictions Management), learn more at http://www.defectivebydesign.org/what_is_drm
Christopher Omega
Oxymoron
Join date: 28 Mar 2003
Posts: 1,828
09-04-2003 22:08
The main, really invonvinant problems with states are:

1. You usually need more global variables so states can share data.

2. There are no state-specific variables, so you need globals to hold and/or transfer state data (globals take up alot of heap btw).

3. Looping across states is an extreme PITA.

4. The translation between states is often slow, as the state_exit() and state_entry() events need to be fired before anything else.

Good things about states:

1. Organizational tools.

2. Ability to taylor events to a specific task, rather then having a crapload of conditional statements and/or booleans to tell what data is coming from the events. Its eiasier to loop across events this way.

3. Easy to clean them up. (state_entry() and state_exit() make for a clean cleanup (heh) and more organization (YAY!) :D.

4. Scripts with states are alot eiasier to read, flowchart, and understand.

...And there you have it! The pros and cons of states (that I can think of).

Personally I love them, TY LL!!!! :)

-Chris
_____________________
October 3rd is the Day Against DRM (Digital Restrictions Management), learn more at http://www.defectivebydesign.org/what_is_drm
Huns Valen
Don't PM me here.
Join date: 3 May 2003
Posts: 2,749
09-11-2003 12:33
There is another small issue. There are lots of small, one-liner scripts floating around out there - one to make an object phantom, the other to rotate textures, etc. Each of these tiny one-liners gets a full heap allocation as well as a timeslice. When several of these are desired on the same object, it is more efficient to combine these into one.
Bosozoku Kato
insurrectionist midget
Join date: 16 Jun 2003
Posts: 452
10-18-2003 05:32
Hun's example code is a nice one. I'd highly suggest it be included in the lsl.chm as a "suggested" method of coding.

Everyone's style differs a fuzz. Mine, for scripts I assume only I'll be looking at, can get pretty sloppy (what I consider sloppy). But I do code pretty much like Huns is, in particular if sharing the code with others.

It's clean and organized. It's commented.

It drives me nuts when I look at a script that hasn't used indenting, has excessive (or NO) linefeeds between events, and long one-line comments.

I do do what Christopher posted, I add short comments after most of my variables (in lue of comment on line above the var). I know a lot of guys don't like this method of commenting, but that's one convention I don't sweat too much :)

Some great suggestions here. I think the main key is keep it simple. Those that haven't worked with *other's* code have nothing to base any conventions on. A short and to the point example (like Huns') is a great solution for a quick tip about coding style.

Boso
Lynn Kukulcan
Registered User
Join date: 7 May 2006
Posts: 149
Coming From QuickBASIC
06-04-2006 08:53
I was told I use a Pascal variable naming system. I use full words, each word capped, no spaces or underscores or anything.

I do not change the naming if variables for contants and local variables and stuff. In fact, to me, this seems to actually clutter the code. After all, why should a variable named "MaximumAltitude" be all capped anyway? Who would change such a variable unless there was a total change in the conditions of the program?

I have discovered that comments on the end of a line of code is inherently confusing. So confusing, in fact, that when I saw virtually every "tutorial" followed this "convention," and pretty well blew my brain out my, well, you know. The long and the short of it? It crossed my wires so badly most of the "tutorial" scripts are useless to me without a major reformatting overall.

I've been buggered about the "i,j,k" thing for a very long time. Why use "i,j,k" when there's "a,b,c?" I just start at the bottom of the alphabet and work my way up. There have been cases where I've had thirteen or fourteen nested loops, so this has proven to be a very handy thing to do.

Indenting is always good. I think a four space indent is a bit excessive, but it does make the code pretty readable, so I'll go with it.

One bit of code I found had spaces around the paranthesis. This is nice, so I'll steal the idea for myself and no one else can have it! Mwahahahaha! }:-)

Well, actually, anyone can use it if it helps. :-)

What else ... ? The suggestions on function names make sense. The only purpose to use extremely short functions would be purely cosmetic. :-)

I tend to remark above my code, and I have a blank line above the remark and one below the segment of code the remark references.

And I think curly brackets should line up.

Not bad for a coder coming from QuickBASIC, huh? :-p

Love & Friendship & Blessed Be!
Lynn Kukulcan
Loretano Dagostino
Registered User
Join date: 12 May 2007
Posts: 3
08-28-2007 14:08
Opened this old thread today by accident and found it interesting that despite of a space I'm using in type-casts my code looks similar to Huns Valen's.

Even after more than 20 years experience as a developer and having used anything from Assembler to LSL I can still not judge over whos code is better. It quite often depends on language, paradigms, project/code size, environment and even cultural common sense.

In my opinion it is not important which rules to apply than to think about it and to use what you and your team feels most comfortable with.