Here are some suggestions for Serpent programming style.
Spaces and Indentation
Indent with 4 spaces. Tell your editor to insert 4 spaces rather than TAB characters. Never use TAB characters because they are invisible and editors treat them differently. See serpent/extras for Sublime and Emacs support files.
Use spaces around all operators: x = a + b / c, not x=a+b/c or even x = a + b/c.
Use space after commas to separate parameters: f(x, y, z + 3), not f(x,y,z + 3).
Use blank lines carefully. With longer functions, blank lines can be used to separate logical blocks of code. Often you will want to put a one-line comment at the beginning of such blocks to describe what the block does:
// create a new named widget
var w = Widget(name)
widget_table[name] = w
// add the widget to the display
Since functions and methods have embedded blank lines, it is best to use at least two blank lines between functions and methods. If methods are separated by double-spaces, perhaps classes and function definitions at the top level should be separated by three blank lines. (This can look too spread out; if it does not help readability, less space often looks better.)
And speaking of comments, use a space after comment tokens:
// good comment with space after “//”
//do not run comments into “//”
# another good comment
#this comment is missing a leading space
Both “//” and “#” are acceptable comment tokens. Since “#” is darker, I prefer to use it sparingly and sometimes to call attention to important points or key 1-line summaries of functions.
Limit line lengths to 80 characters. To write long literal strings, just break the line and use + to join them:
“Pretend this is a very long string of text that requires two lines.”
could be written as:
“Pretend this is a very long string ” +
“of text that requires two lines.”
Long lines also occur in print statements. You can use a trailing comma or semicolon to avoid printing a newline, then continue printing with another print statement:
print “Imagine that this statement is too long for one line”, var1, var2
This can be rewritten as:
print “Imagine that this statement is too long for one line”,
print var1, var2
Similarly, display statements have a trick for long lines:
display “Imagine this is too long for one line”, var1, var2
If a display statement ends in a comma, no newline is printed. If a display statement does not begin with a literal string, it will not generate an initial label from the string, so the following can be used to break the statement into two lines:
display “Imagine this is too long for one line”,
display var1, var2
and the output will be something like:
Imagine this is too long for one line: var1 = 1, var2 = 2
Of course, it can be inconvenient to produce very long output lines as well. If you have one message to output across multiple lines, you can indent lines after the first, e.g.
print “Imagine that this statement is too long for one line”
print ” “; var1, var2
which will print something like:
Imagine that this statement is too long for one line
With display you more-or-less have to use the initial label, but it can be blank, as in:
display “Imagine this is too long for one line”, var1
display ” “, var2
and the output will be something like:
Imagine this is too long for one line: var1 = 1
: var2 = 2
Unlike Python, Serpent comments can begin with // or #. Always follow // or # with a single space before the comment (or multiple spaces if you want to form an indented block of text.) In the author’s opinion, // is prettier than and preferable to #. You can use #, which is darker, for emphasis, e.g. to mark code that needs attention or to provide a one-line summary of each function. Full-line comments should generally precede the thing commented on, and end-of-line comments should follow the thing commented on, e.g.
// pr_range – return integer from low through high – 1
def pr_range(low, optional high)
int(pr_unif(low, high)) // truncate real value
Names and Capitalization
Variable, class, and function names should be descriptive. It is worth a minute to globally rename variables and naming conventions if it makes your code more readable and consistent!
If you want to be consistent with Serpent libraries, use underscores for multi-word variable names, e.g. file_length, and use lower-case everywhere except to capitalize classes, e.g. Labeled_slider. Use all-caps for global “constants,” e.g. NOTE_ON = 0x90.
If you must use “CamelCase,” at least start with lower case for variables and functions, and upper case for classes, e.g. var fileLength and class LabeledSlider.