Coding standard

This document defines and formalizes the style of code produced at Linden Lab. Adherence to these conventions is critical to ensuring readable and maintainable code.

Some tools are available for checking some parts of these rules in the Mercurial Tools repository.

Common Guidelines

Line Endings

All text files must use unix (linefeed only) line endings when submitted.

Exceptions are allowed only if the file in question:

• Is used or relevant only on Windows
• Requires DOS style (carriage-return linefeed) line endings for correctness.

Files that have DOS line endings must either:

• have a suffix that is one of:
  • .bat
  • .sln
  • .vcxproj
• or be located somewhere under a directory named windows or vstool

See How to avoid DOS line endings in Windows tools

Comments

When commenting, address the "why" and not the "what" unless the what is difficult to see. If what the code does requires commenting, also include why it has to be done that way so maintainers can follow your reasoning. Use complete sentences and correct spelling.

Prefer the use of doxygen compatible comment markup. (See Using Doxygen.)

Sometimes you know something is broken or a bad idea but need to do it anyway — please follow the special comment token guidelines to not confuse the next engineer. Append your name or initials and the date of the comment when using these special comment tokens.

Special Comment Tokens

Token	Meaning	Deprecated tokens
*FIX	The associated code is actually broken and has known failure cases. All instances of these should be fixed before shipping. Do not use this tag for hacks or suggested development. Do not simply tag the code with the token alone or simply provide instructions since then it is unclear if that is how it is broken. For example: "// *FIX: invalidate stored textures when number of faces change" — is really unclear if it is an instruction or a buggy side effect of the code segment.	FIXME BROKEN BUG
*HACK	The associated code relies on external information or processes outside the normal control flow for the function to work.	HACK
*TODO	The associated code should be optimized, clarified, or made more reliable. Provide instructions along with why it is probably a good idea to execute on the comment.	TODO
*NOTE	This denotes that there is something tricky or special about the associated code above and beyond answering the typical 'what' and 'why.'	NOTE "NOTA BENE" NB

Examples:

// *FIX: This will fail if the packets arrive out of order. // *HACK: Filter out some extra information from this // packet and put it into the status bar since it is more // up to date than the last balance update. // *TODO: This call does not always need to be made // and is computationally expensive. Write a test to see // if it must be made during this iteration. // *NOTE: The tile is actually 257 pixels wide, so // we have to fudge the texture coordinates a bit for this // to look right.

No New Serialization Formats

After much effort and unit-testing, LLSD is now the sanctioned format for all new serialization tasks. Do not implement another serialization scheme unless you have a signed and notarized letter from Elvis explicitly stating that a new serialization format is a good idea. If speed is essential, LLSD has a fairly speedy binary parser and formatter available in C++ and python.

Unicode

Use UTF-8 for all string serialization and communication between processes. Do not use UTF-16 except when interfacing with Win32.

File Names

File names should be significant and of reasonable length, with no spaces or uppercase letters. Separate words in the name MUST be separated with underscore (like_this.cpp), because languages like Python cannot include module names with hyphens (will-not-import.py).

Dead Code

Do not leave commented-out code in any commits that you make. Delete that code instead.

Block-commented out code, including code disabled through #if <something-false> is especially problematic because it is not distinguishable from live code in a grep. Our version control systems are good enough that any code that was checked in is retrievable even after deletion.

C++

Source Files

All C++ source code files should begin with the header shown below:

/** 
 * @file file base name
 * @author optional
 * @brief brief description of the file
 *
 * $LicenseInfo:firstyear=2011&license=viewerlgpl$
 * Second Life Viewer Source Code
 * Copyright (C) 2011, Linden Research, Inc.
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License only.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 * $/LicenseInfo$
 */

The $LicenseInfo$ section is critically important so that we can process the source files based on license agreements. If you're unsure, use viewerlgpl. The licenses we support are:

• internal - something probably not meant for distribution unless we have an agreement with the third party.
• viewergpl - deprecated this was used for pre-Snowstorm viewer distribution
• viewerlgpl - the viewer and linden libraries distributed with it
• mit - a basic MIT license for some libraries such as mulib, eventlet, and indra.ipc.

Replace the 2011 with the year the file is created.

All C++ source files should end in a newline. If not, GCC will fail with an error, as it enforces the C++ standard which requires one.

Headers should be included in the following order:

// All files MUST include one of the following first: 
//  (includes linden_preprocessor.h, stdtypes.h, and some common headers)
#include "llviewerprecompiledheaders.h"	// (NEWVIEW)
// OR
#include "llsimprecompiledheaders.h" // NEWSIM
// OR
#include "linden_common.h" // the ll libraries

#include "llfoo.h"		// Associated header, should have no hidden dependencies

#include <map>			// stl headers
#include <cmath>		// std headers
#include "vorbis/ogg.h"		// External library headers

#include "llbar.h"		// Other linden headers

File Names

All C++ source files should be prefixed with 'll'.

File names must end with the appropriate suffix:

• cpp for ANSI C++ code
• h for included declarations
• inl for large chunks of inlined C++ code. Avoid this.
• asm for assembly files. Do not do this without a note from some deity forgiving your transgressions.

Include Files

Include files should be specified using relative paths using the '/' character to help ensure portability. In the code relative paths should not be used. Instead, paths should be indicated in the relevant CMake file.

Compiler directives used to prevent multiple header file inclusion should be based on the file name with a LL_ prefix. Include dependent headers in the header file, but use forward declarations where possible.

For example:

#ifndef LL_LLFOO_H
#define LL_LLFOO_H

#include "llbar.h"

class LLReferencedData; // forward declaration (no need to include "llrefrenceddata.h")

class LLFoo : public LLBar
{
public:
    LLFoo();
    void setData(LLReferencedData& refdata);
private:
    LLReferencedData* mRefData;
};

#endif //LL_LLFOO_H

Basic Facilities

Linden Variable Types

The following basic types are defined in "stdtypes.h" and should be used to ensure clarity and cross platform functionality:

• Integral Types
  • The first letter specifies 'S' for signed integers and 'U' for unsigned integers
  • The type ends with the number of bits used to represent the integer
  • Examples: S8 (signed 8-bit integer), U32 (unsigned 32 bit integer)
  • The integer types are: U8, S8, U16, S16, U32, S32, U64, S64
  • The char type may used when required by defualt C functions that need a char
• Floating Point Types
  • F32 denotes a 32-bit floating point value ("float")
  • F64 denotes a 64-bit floating point value ("double")
• Other Types
  • Prefer the use of the standard C++ bool. This is especially for comparators like operator< (using bool instead of BOOL will prevent lots of warnings when using STL). BOOL denotes a 32-bit integer value that is used to denote TRUE or FALSE. It is specifically not bool to prevent mistakes caused by "sizeof(bool)" being implementation specific.

Project Defines

• Use LL_WINDOWS, LL_LINUX, and LL_DARWIN for platform specific code.
• Use LL_RELEASE and LL_DEBUG for release and debug specific code.
• LL_RELEASE_FOR_DOWNLOAD and LL_RELEASE are both defined in versions destined to be in a resident's hands.
• Prefer testing for the positive when using #if, and use #if/#if ! instead of #ifdef/#ifndef. For example:

#if LL_DEBUG && !LL_DARWIN

instead of:

#ifndef LL_RELEASE && !defined(LL_DARWIN)

However, this construct is still useful:

#ifndef SOMETHING
#define SOMETHING SOMETHING_NEW
#endif

Usage

String Handling

See C++ Strings for more guidelines on strings in the C++ codebase.

Use std::string as a string container and the STRINGIZE() macro for constructing strings from multiple sources.

If you must use printf style formatting, use snprintf() or llformat(). Never use user supplied data (including configuration files) to specify formatting instructions to those functions.

Avoid using c-string libraries. If you are writing something where speed is critical, prefer the use of std::vector<char> since it's usage is less error prone, you can explicitly allocate or occupy memory, it is easy to null terminate with a single call to container.push_back('\0'), and it is char* compatible with a call to &container[0].

The following c functions are forbidden:

• sprintf() and vsprintf() — most of the printf family of functions are like individual invitations to hackers to overflow a buffer. Don't use them.
• strcpy() and strncpy() — both of these functions are dangerous and difficult to use correctly. For example, did you know that strncpy() does not null terminate if no null is found in the source?
• strcat() and strncat() — these methods are inefficient in comparison to using ostringstream() and are easy to misuse. The strncat() function is almost forgivable, but please just avoid these.
• gets() — Never, ever use this function.

Our legacy being what it is, there are some unavoidable cases where we are forced to use c-string functions. Here are some tips:

• sscanf(), fscanf(), etc... — For these methods, always supply a maximum width for strings. If you do not know how to do this off the top of your head, do not use these functions. Even if you think you know, read the man page again.
• snprintf(), fprintf(), vsnprintf(), etc.. — As noted above, never let anything other than the program determine the formatting. Never trust configuration files, assets, message system data, etc.

Unicode

Useful functions for dealing with UTF-8 can be found in llstring.h. Remember that truncating a UTF-8 string must be done on glyph rather than byte boundaries or your string may no longer be valid UTF-8. Many methods in std::string and LLString are not UTF-8 safe since they work on sizeof(char_t) byte boundaries. Similarly, the functions in that header file which do not contain 'ut8f' in the prototype are probably not UTF-8 safe.

Do not use UTF-16 except with interfacing with Win32.

Avoid the use of wide strings except when iteration speed is essential, or you are interfacing with the host operating system.

Trigraphs

A trigraph is a set of three characters that represents one character in the C character set. The set of trigraph sequences was defined in the ANSI Standard to allow users to use the full range of C characters, even if their keyboards do not implement the full C character set.

Each trigraph sequence is introduced by two question marks. The third character in the sequence indicates which character is being represented. The standard trigraphs and the characters they produce are:

??(   [
??/   \
??)   ]
??'   ^
??<   {
??!   |
??>   }
??-   ~

Using trigraphs anywhere in Second Life code is not allowed.

Containers

Prefer the use of the containers available in the C++ standard template library. They are well tested and in common usage across the industry — thus, nobody has to learn the special (and lame) quirks of containers like LLMap<> and LLLinkedList<>.

This is one of the few places where specialized implementations can yield significant memory or speed improvements. Do not create those containers until you have profiling results that prove the container is the bottleneck.

Never use std::vector<bool>.

Memory Management

Object allocation and deallocation should always be done using new and delete (or delete[] where appropriate).

Wherever possible, going forward, object lifetime should be managed using smart pointers, favoring the shared_pt, weak_ptr and unique_ptr types. When defining a pointer type declare a typedef to make it easily referenced elsewhere in the code, this typedef should be of the form:

typedef boost::shared_ptr<Class> ClassPtr; 
typedef boost::intrusive_ptr<Class> ClassPtr;

and

typedef boost::weak_ptr<Class> ClassWPtr;

Alternately, a class may define its own preferred pointer type as part of its definition.

class MyClass 
{
    typedef boost::shared_ptr<MyClass> ptr_t;
    typedef boost::weak_ptr<MyClass> wptr_t;
};

/.../

MyClass::ptr_t aPointerVariableToMyClass;

New uses of the internal LLPointer<T> class should be avoided.

For legacy deallocation , not yet handled by managed pointers, remember that C++ defines delete NULL as being safe, therefore it is unnecessary to test for NULL before deleting.

delete var;
var = null;

Exception Handling

Exceptions have been recently enabled for all platforms and targets in the main indra code base. If you are familiar with their use, you can use them judiciously in the code. Be sure to make sure the places where you are throwing exceptions will not cause resource leaks, and be sure to comment what linden exceptions might be thrown with the function declaration.

• do not use exception specifications
• do not throw in a destructor (ever)
• read up on exceptions before using them

Resources

• C++ FAQ
• exceptional C++
• more exceptional C++

Error Messages

• See Logging_System_Overview for detailed info on using the runtime logging system. (Test plan for logging system found at: Configurable Error Logging Test)
• Do not wrap your messages in #ifdef _DEBUG, unless it is inside a performance critical loop. The logging constructs compile to very small amounts of code, and are very efficiently skipped at run time. And the ability to turn on your debug messages at run-time, even in a deployed release build, will make you very happy one day.

Obvious Things We All Know

• No magic numbers
• Use TRUE and FALSE when working with BOOL (but prefer bool in general)
• Use NULL for pointer compares to 0
• Use '\0' for character compares to 0
• Use const and inline rather than #define whenever possible. Prefer optimizing after you have proven that the code you want to inline actually has a significant benefit from in-lineing.
• Remember that C++ does not have garbage collection
• Comment non-intuitive member variables
• Fix all compiler warnings.
• Take advantage of the fact that gcc generates different, sometimes better, warnings than Visual Studio.
• Don't use assignments in while loops, e.g. while (foo = nextData()) as this causes gcc to emit warnings. Use while ((foo = nextData()) != NULL) or restructure the code.

Style

Naming Convention

The following name conventions apply to non-iterators:

• Names should include one or more English words that are relevant to the entity being named. Try to use non-programming words, like EmployeeList rather than LinkedListOfStrings
• C functions are in lowercase, e.g. main(), update_world_time()
• Local variables and parameters are in lowercase, e.g. frame_count
  • Local variables are not camel-case. thisIsNotALocalVariable
• Class methods start with a lowercase character but are otherwise CamelCase, e.g. destroyWorld()
• Non-static class member variables start with an 'm' followed by an uppercase character, e.g. mCameraPosition
• Static class member variables start with an 's' followed by an uppercase character, e.g. sInstance
• Structures and Classes start with the uppercase 'LL', followed by the name with an uppercase first letter, e.g. LLMyClass
• Enums start with the uppercase 'E', followed by the name with an uppercase first letter, e.g. EJerkyType. The enum values themselves should use the initials of the type, e.g. JT_TURKEY, JT_BEEF, etc.
• Variables are in MKS (meters, kilograms, seconds) unless otherwise specified, e.g. frame_time is seconds, frame_time_ms is milliseconds.
• Data sizes are bytes unless otherwise specified, e.g. size vs. size_bits.
• Global variables start with a lowercase 'g', followed by the name with an uppercase first letter, e.g. gGlobalTimeCounter
• Compiler preprocessor directives should start with LL_ and consist of all uppercase letters separated with underscores, e.g. LL_DEGREES_TO_RADIANS()
• Externally available const global variables that replace #defines should start with LL_ and consist of all uppercase letters separated with underscores, e.g. LL_SECONDS_IN_DAY
• File scoped const global variables that replace #defines need only consist of all uppercase letters separated with underscores, e.g. SECONDS_BETWEEN_CLEANUP
• You may optionally append a suffix character signifying the type, for example, fontp is a font pointer, mTimeInSecondsf is a float

Enums

Enums generally are declared using this form:

typedef enum e_new_enum
{
  NE_ALPHA,
  NE_BETA,
  NE_GAMMA
} ENewEnum;

so that the typedef name (ENewEnum in the example) can be used as a type name rather than (enum e_new_enum).

Class Structure

Member functions come first, followed by member variables at the end. Write it assuming a time-pressured programmer is going to read it from top to bottom looking for something they can use, so put the exported functions at the top, eg:

class LLMyClass	
{
public:
	LLMyClass();
	~LLMyClass();

	void		init(S32 area, F32 priority);

	void		setVariable(BOOL variable)	{ mVariable = variable; }
	virtual void	draw();

private:
	BOOL		mVariable;
        static U32      sCount;
	etc.
};

• Optionally, one line functions may be written in the class declaration header. Functions inlined for speed should go in the header. Other functions should go in the .cpp file.

  NOTE: Functions inlined this way do not require the inline compiler hint

  NOTE: virtual functions can not be inlined by the compiler so they should reside in the .cpp file because

  • otherwise the linker has to resolve each instance into a single function
  • it is misleading to imply that the function will be inlined when it will not be (e.g. don't use virtual functions inside performance critical inner loops)

• Make sure that you initialize ALL member variables prior to use (often easiest to use an init() member function).

Interface Naming

C++ Interfaces follow the above conventions for normal classes. They must consist entirely pure virtual methods and have a pure virtual destructor. Interfaces must be named with Interface postfix.

class LLExampleInterface
{
public:
    virtual ~LLExampleInterface() = 0;

    virtual void example() = 0;
};

Member Visibility

Class declarations represent contracts and all non-private members are promises. It's important to promise as little as possible because it's much easier to expose more functionality later than it is to take it back. It also requires less precious time from each programmer attempting to use a given class when the non-private members are kept to a minimum. If you see something that's private, you know that you can safely ignore it, otherwise the designer is signaling that it is something that you might potentially want to use. Therefore please use these guidelines to keep visibility to a minimum, and remember that everything that applies to data members also applies to typedef, enum, class and method members.

• Prefer protected members to public, and prefer private members to both.
• Prefer private inner classes to friends.
• Document all non-private members but only document implementation details in the .cpp file.
• Avoid creating a member in the first place when not absolutely needed. E.g. implement getNumPixels() { "return mWidth * mHeight; } rather than getNumPixels() { return mArea; } and having to always make sure that mArea is kept in sync with the current width and height. Remember: All class members are global to the class and all standard wisdom regarding globals apply.
• Prefer accessor methods to accessible data.
• Prefer local variables to member variables. Sometimes people create member variables as a way to share data between methods. When possible, it's better to create a local variable in one method and pass it as an argument to the ones that needed it.
• Declare local variables as close to their point of use as possible. I.e. within nested blocks and as far down within its block as possible.

Static Members

Use static class members for global variables and singletons. Since these are globals, avoid using statics when practical. Avoid static class instances which will be globally constructed, use pointers and construct them in an initializer instead.

class LLFoo
{
    static LLFoo* sInstance; // Don't do this -> static LLFoo sInstance;
    static void initClass();
};
...
//static
LLFoo* LLFoo::sInstance = NULL;

//static
void LLFoo::initClass()
{
    sInstance = new LLFoo();
}

Indentation

1. Configure your editor to treat a tab as having width of 4.

   Adding tabs that assume any other tab width is forbidden, and makes you look bad.

2. The use of either spaces or tabs for indentation is allowed, but spaces are preferred.

Note: An earlier version of this standard required tabs, so much of the codebase uses them. Do not convert existing tabs to spaces unless you are either making significant changes to the code or are willing to do all merges on that file for anyone who needs them.

When possible, use indentation to clarify variable lists and Boolean operations.

Braces

Source code should be written using braces on a line by themselves, similar to the gnu standard (not the more compact k&r standard), i.e.

while (foo < 10)
{
}

Instead of:

while (foo < 10) {
}

And:

do 
{
    do_stuff();
} while (foo < 10);

Instead of:

do {
    do_stuff();
}
while (foo < 10);

And:

if (foo < 10)
{
    do_stuff();
}
else
{
    do_stuff();
}

Instead of:

if (foo < 10) {
    do_stuff();
} else {
    do_stuff();
}

Use braces for clarity, even when not strictly required, e.g.

for (j = 0; j < NUM_TEXTURES; ++j)
{
    do_stuff();
}

Instead of:

for (j = 0; j < NUM_TEXTURES; ++j)
    do_stuff();

Comments

Use C++ style comments for single line comments and member variable descriptions. Use classic C style comments /* */ for temporarily commenting out large sections of code.

We use the Doxygen system for generating documentation from header and source files. Doxygen supports a wide range of styles; this section provides recommendations for how it should be used in the Second Life Viewer project.

Doxygen Comment Style

Doxygen comments are distinguished from normal comments by an extra comment character at the beginning, and are associated with the adjacent code by their placement. Both C style comments and C++ single-line style comments are supported.

C++ single-line style comments

Doxygen interprets any C++ comment that has a '!' character at the beginning of a '//' comment, or an extra '*' character at the beginning of a '/* ... */' comment:

 //! A Doxygen single line comment

 /** A Doxygen single line comment */

C multiple-line style comments

 /// A Doxygen comment
 /// that extends over more than one line
 /// this form should be used whenever there is more than one line

note that triple slash does not work as a single line comment - it must have at least two lines

Comment Placement

Doxygen comments are, by default, associated with the code that immediately follows the comment:

 //! indicates whether or not the object currently allows any Foo actions.
 void isFooAllowed();

For some constructs it is more readable to place the comment after the code element it documents, which is accomplished by adding a '<' character after the Doxygen comment indicator. This may be used with either single or multi-line comments:

 void doFooAt( int offset ///< the offset into the Foo
              ,char* name ///< the name to look up for this Foo action
                          ///  in the FooMgr database.
             );

Placing the Doxygen comment after the element it documents in this way is preferred whenever the element is a member of a list, as in parameter declarations or enum values.

Class Documentation

A class declaration must include a detailed description comment preceding the class:

 /// FooFactory is a factory class that constructs instances of the
 /// subclasses of Foo based on information obtained from the
 /// foo-config file.
 class FooFactory
 {

The class comment is a good place to put general guidelines about how the methods in the class relate to one another.

Member Grouping

By default, Doxygen groups the members within a class based on heuristics that use the public/protected/private scope and the method signatures. For simple classes this usually works well, and may be used. When a class has many methods, it is usually better to explicitly control how they are grouped in the documentation, and to provide additional documentation at the group level. To explicitly control grouping, add the 'nosubgrouping' Doxygen command to the class comment:

 /// FooFactory is a factory class that constructs instances of the
 /// subclasses of Foo based on information obtained from the
 /// foo-config file.
 ///
 /// @nosubgrouping
 ///
 class FooFactory
 {

Each group is then formed of the following elements:

• An introducing Doxygen comment that supplies the group name using the 'name' Doxygen command,
• The detailed comment for the group,
• The Doxygen group start command '{',
• The declarations of the members in the group and accompanying documentation, and finally
• The Doxygen group end command '}'.

For example (preceeded here by a non-Doxygen comment with a line of '=' characters so that it reads better in the source file):

 // ================================================================================
 /// @name Searching
 ///
 /// The searching methods apply a compiled regular expression to a subject
 /// string.  All searching methods return a boolean result indicating whether
 /// or not some match was found in the subject.  To get information about
 /// the match, use the Results methods.
 ///
 ///@{
 ... the methods in the group ...
 ///@}

Member Function Documentation

Each member function should have:

• A brief single line description preceeding the member declaration
• Parameter descriptions following each parameter
• A more detailed description following the declaration, which should include a Doxygen 'returns' command if the method returns a value.

 /// Search a string for matches to this regular expression.
 bool Search( const char * subject ///< the string to be searched for a match
             ,int len = -1         ///< the length of the subject string
             ,int options = 0      ///< sum of any PCRE options flags
             );
 ///<  Apply the regular expression to the subject string.
 ///   Optional parameter len can be used to pass the subject's length to
 ///   Search(). If not specified (or less than 0), strlen() is used
 ///   internally to determine the length. Parameter options can contain
 ///   any combination of options; for options documentation, see 'man pcre'
 ///   @returns true if a match is found.

Usage Examples

Including examples in the documentation is strongly encouraged. To embed an example, use the Doxygen "@code ... @endcode" construct:

 ///<
 /// May only be called after a successful search
 /// and applies to the results of that call.
 /// @returns true if there was an ith match, false if not
 ///
 /// Example:@code
 /// RegEx matchBs("((B)B+)");
 /// UtlString getB;
 /// UtlString getBs;
 /// if (matchB.Search("xxaBBBBcyy"))
 /// {
 ///   matchB.MatchString(&getBs,0);
 ///   matchB.MatchString(&getB,2);
 /// }
 /// @endcode
 /// would set the UtlStrings
 ///  - getBs to "BBBB"
 ///  - getB  to "B"

Lists

Numbered and bulleted lists are supported in Doxygen comments using simple indentation conventions:

 ///< A numbered list is created using '#' characters:
 ///  # first numbered item
 ///  # second numbered item
 ///    # first item in nested numbered list (2.1)
 ///
 /// A bullet list uses '-' characters:
 ///  - first bullet
 ///  - second bullet
 ///    - nested bullet

Function Declaration

The return value of the function should be on the same line as the function name, e.g.

void foo_func(S32 bar)
{
	// do stuff
}

Python

Our Python coding standards are generally based on http://www.python.org/dev/peps/pep-0008/, which should be considered authoritative for anything not covered here.

pylint can be used for stylistic as well as error checking. E.g. pylint --reports=n mydcode.py

Source Files

Unless it is an executable script, begin all Python source code files with this header:

"""\
@file filename
@author Optional author field
@date Optional iso8601 creation date
@brief brief description of the file

$LicenseInfo:firstyear=2011&license=viewerlgpl$
Second Life Viewer Source Code
Copyright (C) 2011, Linden Research, Inc.
 
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation;
version 2.1 of the License only.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
$/LicenseInfo$
"""

The $LicenseInfo$ section is critically important. Choose viewerlgpl if you are not sure.

Python File Names

There is no need to prefix 'll' to every source file, but it may still be appropriate for the filename, for example, llsd.py.

Write Python scripts intended to be executed from the command line in a way that makes them importable as a module. This means you should structure your code as follows:

#!/usr/bin/env python
#
# Doxygen header and license, see above
...

# Preamble, see below
...

# any class / utility functions here
...

# the main "api" function
def do_stuff(arg1, arg2 ...):
   ...

# the main() function which does the command line parsing and validation
# and invokes the "api" function.
def main(argv):
   ...
   return exit_code

# execute main() only if invoked directly:
if __name__ == "__main__":
    sys.exit(main(sys.argv))

Style

Library modules should never call functions or create objects which have side effects in the global process state prior to the first function call or object instantiation from an outside caller. This makes sure that different callers can configure the process state as necessary and not allow incorrect default values seep into the process state.

# replace this:
CONSTANT = 'value'

# with this:
_g_constant = None
def get_constant():
    global _g_constant
    if _g_constant is None:
        _g_constant = 'value'
    return _g_constant

Whitespace

Python can't parse files that mix using tabs and spaces for indentation. We settled on 4 spaces as the standard indentation increment.

Put this in your ~/.emacs to get the desired behavior (note that this also turns on colored fonts, which you probably wanted anyway):

(defun ll-python-mode-hook()
  (font-lock-mode 1)
  (font-lock-fontify-buffer)
  (set-variable 'indent-tabs-mode nil)
  (set-variable 'py-indent-offset 4)
  (message "ll coding style function executed"))
(add-hook 'python-mode-hook 'll-python-mode-hook)

(insert instructions on using python-mode if it's not with your default emacs install)

To convert tabs to spaces in Emacs:

• Make sure your tab width is 4
  • In .emacs, (set-variable 'tab-width 4) (optionally inside your ll-python-mode-hook())
  • Immediately: M-x set-variable[ret] tab-width[ret] 4[ret]
• Set mark at start of file: M-< ^space
• Jump to end of file: M->
• Convert tabs to spaces within marked range: M-x untabify

To use spaces instead of tabs in vi put this in ~/.vimrc:

" You probably already have these
set tabstop=4
set shiftwidth=4
" When reading a file or creating a new file, uses spaces not tabs
autocmd BufRead,BufNewFile *.py set expandtab

Another option for tabs/spaces:

" automatically expand tab keypresses into the appropriate number of spaces
set expandtab

PYTHONPATH

To write scripts that can be run without an explicit PYTHONPATH, see linden/scripts/setup-path.py and the scripts that reference it.

We maintain a python library in indra/lib/python. In order to use the libraries in there, you have to set the PYTHONPATH environment variable to point to that directory, e.g.

PYTHONPATH=/var/tmp/rdw/release/indra/lib/python python test.py

To avoid having to specify the PYTHONPATH, you can instead use this snippet of code:

import sys
import os.path
 
# Look for indra/lib/python in all possible parent directories ... 
# This is an improvement over the setup-path.py method used previously:
#  * the script may be relocated anywhere inside the source/runtime tree
#  * it doesn't depend on the current directory
#  * it doesn't depend on another file being present.

def add_indra_lib_path():
    # Use a function to ensure that global scope isn't polluted
    root = os.path.realpath(__file__)
    # always insert the directory of the script in the search path
    libdir = os.path.dirname(root)
    if libdir not in sys.path:
        sys.path.insert(0, libdir)

    # Now go look for indra/lib/python in the parent dirs
    while root != os.path.sep:
        root = os.path.dirname(root)
        libdir = os.path.join(root, 'indra', 'lib', 'python')
        if os.path.isdir(libdir):
            if libdir not in sys.path:
                sys.path.insert(0, libdir)
            return root
    print >> sys.stderr, "This script is not inside a valid installation."
    sys.exit(1)

# Use the return value to locate other files relative to the
# install root...
_root = add_indra_lib_path()

Symlinking /opt/linden to your checkout should be deprecated. That's a bad dependency to have, and it doesn't play well with multiple devs on a station.

On our machines, we now have a standard library in /var/lib/python-support.python2.4/llindrapath.py that does all this. As such, you should be able to accomplish the path by including this line:

import llindrapath

imports

• Include only one module per line
• Order your imports alphabetically (this gets a little vague with from x in y imports TODO: invent a rule that makes sense)
• Try not to pollute the module's namespace by importing individual functions and classes from other modules.

bad:

<python> from os.path import join, dirname, realpath import socket, urllib2 </python>

good:

<python> import os.path import socket import urllib2 </python>