You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

IDL Best Practices

We're currently working on this documentation. New stuff will be added on an ongoing basis. Please send any questions or comments to netscape.public.mozilla.xpcom.

enums and consts
    Constants defined inside an interface in XPIDL appear as JavaScript properties of instances of classes that implement that interface. Recall that constants must be of type short or long. It is possible to implement constants of other type (string, for example) by holding the value in an attribute of the interface, or returning it through a method.
    XPIDL codeExample JavaScript
    interface nsIFoo {
      const short ONE = 1;
    var myFoo = Components.classes[";1"].CreateInstance();
    var myFoo = myFoo.QueryInteface(Components.interfaces.nsIFoo);
Return types
    You should use a return type other than void so that script writers will be able to use the return value directly. (In C++ the return value is converted into a trailing out parameter.)
native and raw C++ types

    Any interface that contains native or raw C++ types cannot be made scriptable. The XPIDL compiler will treat it as an error if an interface or method is marked as scriptable and it contains native or raw C++ types.

    Individual methods in an interface may be marked as not scriptable by using the [noscript] attribute before the problem method. Methods marked with [noscript] will not be available for use from scripting languages.
    XPIDL codeComment
    [ptr] native nsNativeType(nsFileSpec);
    [scriptable] interface foo {
      void BadMethod(in nsNativeType aNativeType);
    Compiler exits with error:
    cannot_script.idl:4: Error: methods in [scriptable] interfaces which are non-scriptable because they refer to native types (parameter "aNativeType") must be marked [noscript]
    [ptr] native nsNativeType(nsFileSpec);
    [scriptable] interface foo {
      [noscript] void BadMethod(in nsNativeType aNativeType);
    C++ header file is generated as normal. BadMethod is not available from JavaScript.

String Passing

    All strings that are returned through out parameters in C++ must be allocated using the nsIAllocator so that the string's lifetime can be managed by XPConnect. If a string is not allocated with nsIAllocator, then the string will get lost, resulting in a memory leak or crash.

    See the XPConnect FAQ item "How do I make 'out string' work right?" for details on how to properly pass strings out of a method.

Method Names

    When choosing method names in your interface, it's best to use the interCaps style - leading lower case, subsequent units within the identifier capitalized. This matches existing JavaScript convention and will look natural to scripters.

    The dominant C++ method name convention within Mozilla is to use InterCaps style (leading upper case.) To support this, the xpidl compiler capitalizes method names when generating C++ headers. Even if you're creating IDL for an existing interface with an InterCaps C++ implementation, it's still best if you use interCaps. It'll look familiar to JavaScript authors, and your C++ will still work.

[Rules and Syntax] [Best Practices] [Keywords]

Mike Ang
Mike McCabe
Last modified: Tue Oct 5 14:45:25 PDT 1999