IDL interface rules
[email protected] (Alec Flett) Thu, 05 Sep 2002 09:01:22 -0700
| Newsgroups | gmane.comp.mozilla.devel.xpcom |
|---|---|
| Message-ID | <[email protected]> |
Here's the first revision of an IDL interface rules document that I've put together. Developers, please read over this document to learn how to write proper scriptable interfaces. Reviewers, direct people to this document whenever you review code with bad IDL.... Everyone, I'm looking for more rules/advice/suggestions.. One thing I'm going to add is a section on types (mapping to C++, etc) http://www.mozilla.org/projects/xpcom/interface-rules.html
www.mozilla.org/projects/xpcom/interface-rules.html
(text/html, 10.9 KB)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<title>IDL interface rules</title>
<link rel="StyleSheet" href="Standard.css" type="text/css">
<LINK REL="stylesheet" HREF="../../persistent-style.css" TYPE="text/css">
<LINK REL="icon" HREF="../../images/mozilla-16.png" TYPE="image/png">
</HEAD>
<BODY>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" WIDTH="100%">
<TR>
<TD VALIGN="TOP" class="bannercell">
<A HREF="http://www.mozilla.org/" CLASS="bannerlink">
<IMG SRC="../../images/mozilla-banner.gif" ALT=""
CLASS="mozillaorgbanner" WIDTH="600" HEIGHT="58">
</A>
</TD>
</TR>
</TABLE>
<TABLE BORDER="0" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR>
<TD VALIGN="TOP" >
<TABLE BORDER="0" class="outersidebar"><TR><TD class="bordercell" VALIGN="TOP">
<TABLE BORDER="0" CELLSPACING="3" class="middlesidebar"><TR><TD class="titlecell" VALIGN="TOP">
<TABLE CELLPADDING="0" CELLSPACING="3" BORDER="0" class="innersidebar">
<TR><TD class="linkcell" COLSPAN=2><A HREF="../.././"><B> The Mozilla<BR>Organization</B></A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../mozorg.html"> At A Glance</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../feedback.html"> Feedback</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../get-involved.html"> Get Involved</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../community.html"> Newsgroups</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../MPL/"> License Terms</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="http://www.mozilla.org/newsbot/"> Newsbot</A></TD></TR>
<TR><TD class="spacercell"></TD></TR>
<TR><TD class="linkcell" COLSPAN=2><A HREF="../../catalog/"><B> Developer Docs</B></A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../roadmap.html"> Roadmap</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../projects/"> Projects</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../ports/"> Ports</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../owners.html"> Module Owners</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../hacking/"> Hacking</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../source.html"> Get the Source</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../build/"> Build It</A></TD></TR>
<TR><TD class="spacercell"></TD></TR>
<TR><TD class="linkcell" COLSPAN=2><A HREF="../../quality/"><B> Testing</B></A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../releases/"> Download</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../quality/help/bug-form.html"> Report A Bug</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../bugs/"> Bugzilla</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="../../quality/bug-writing-guidelines.html"> Bug Writing</A></TD></TR>
<TR><TD class="spacercell"></TD></TR>
<TR><TD class="linkcell" COLSPAN=2><A HREF="../../tools.html"><B> Tools</B></A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="http://lxr.mozilla.org/seamonkey/"> View Source</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="http://tinderbox.mozilla.org/showbuilds.cgi?tree=SeaMonkey"> Tree Status</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="http://bonsai.mozilla.org/cvsquery.cgi?treeid=default&module=SeaMonkeyAll&branch=HEAD&branchtype=match&dir=&file=&filetype=match&who=&whotype=match&sortby=Date&hours=2&date=day&mindate=&maxdate=&cvsroot=%2Fcvsroot"> New Checkins</A></TD></TR>
<TR><TD></TD><TD class="linkcell"><A HREF="http://bugzilla.mozilla.org/"> Submit A Bug</A></TD></TR>
<TR><TD class="spacercell"></TD></TR>
<TR><TD class="linkcell" COLSPAN=2><A HREF="../../faq.html"><B> FAQ</B></A></TD></TR>
<TR><TD class="linkcell" COLSPAN=2><A HREF="http://www.mozilla.org/search.html"><B> Search</B></A></TD></TR>
</TABLE>
</TD></TR></TABLE>
</TD></TR></TABLE>
</TD>
<TD VALIGN="TOP">
<h1>IDL interface rules</h1>
<p> This document describes some do's and don'ts when writing an interface in IDL for mozilla.
</p>
<p>
Rule: Use interCaps for naming. All methods and attributes should begin with a lowercase letter. Every subsequent word in the method or attribute name should be capitalized. Avoid capitalizing first letters and using underscores to seperate words.<br>
Why: IDL usually follows JavaScript convention, which is intercaps. In addition, the first letter of all names are promoted to upper case in C++. The C++ signature is the same whether or not the first letter is capitalized.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* don't capitalize first letters! */<br>
void OpenFile(in nsIFile file);<br>
attribute AString Filename;<br>
/* Avoid underscores! */<br>
attribute long unknown_entries;<br>
</div>
<li>Good:
<div class="source-code">
void openFile(in nsIFile file);<br>
attribute AString filename;<br>
attribute long unknownEntries;<br>
</div>
</ul>
<p>
Rule: Use attributes wherever you are referring to a single, non-dynamic value.<br>
Why: Scripted access to the interface is easier to read. Combining two get/set methods into a single attribute also syntactically shows their relevance. Methods also imply some sort of action or side effect.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* These refer to the same value, why make them functions? */<br>
long getColorValue();<br>
void setColorValue(in long value);<br>
<br>
/* we just want a getter, but we can still use an attribute!<br>
 * besides, a method implies an action. */<br>
long brightness();<br>
</div>
<li>Good:
<div class="source-code">
attribute long colorValue;<br>
readonly attribute long brightness;
</div>
</ul>
<p>
Rule: Avoid excessivly long names, but keep them readable. Don't abbreviate words. Avoid names that involve prepositions like "of" or "on"<br>
Why: Its easier to use methods/attributes with shorter names, but it is easy to confuse shortened names, especially for non-english speakers.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* seems a bit verbose */<br>
readonly attribute long numberOfEntries;<br>
<br>
/* why shorten this? is this Attribute? Attrition? */<br>
long getAttrCount(in ACString name);<br>
</div>
<li>Good:
<div class="source-code">
readonly attribute long entryCount;<br>
long getAttributeCount(in ACString name);<br>
</div>
</ul>
<p>
Rule: Use ACString to represent ASCII strings or binary string-like data.<br>
Why: The "A" string classes are more efficient than the "string" type. They include the length of the string passed in, and avoid excess allocations. They also allow for subfragments of existing strings without copying, and multi-fragment strings.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* use the new string classes! */<br>
void processName(in string name);<br>
<br>
/* high bit will get stripped by XPConnect. is that ok? */<br>
void fillBuffer(in string data);<br>
<br>
/* new string classes will avoid excess allocation,<br>
* especially when the caller uses nsCAutoString */<br>
void getHeaderValues(out string prefix, out string postfix);<br>
</div>
<li>Good:
<div class="source-code">
void processName(in ACString name);<br>
void fillBuffer(in ACString data);<br>
void getHeaderValues(out ACString prefix, out ACString postfix);<br>
</div>
</ul>
<p>
Rule: Use AString or UTF8 string to represent unicode strings. Avoid the "wstring" type where possible.<br>
Why: The "A" string classes are more efficient than the old "wstring" type. XPConnect will properly convert to/from UTF8.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* Even if errorMsg is UTF8, it will get corrupted by XPConnect */<br>
void displayError(in string errorMsg);<br>
<br>
/* use AString to allow fragment to have a length */<br>
void parseFragment(in wstring fragment);<br>
</div>
<li>Good:
<div class="source-code">
void displayError(in AUTF8String errorMsg);<br>
void parseFragment(in AString fragment);<br>
</div>
</ul>
<p>
Rule: Avoid out parameters, especially when a method has only one out parameter. Use the return value of a function instead<br>
Why: out parameters are extra work for scripts, which must create a temporary object to hold the resulting value.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
/* This will be frustrating to call from a script */<br>
void getHeaderValue(in ACString header, out AString value);
</div>
<li>Good:
<div class="source-code">
AString getHeaderValue(in ACString header);
</div>
</ul>
<p>
Rule: Try to #include only other .idl files. If you need access to a C++0only type, try to predeclare it and rely on C++ consumers to #include the correct header.<br>
Why: Generated C++ headers will differ from the IDL, causing confusion as to what classes have been defined. If you predeclare a type and then #include a .h file in order to get the definition, you may have problems with the generated header if the #included .h file changes later.
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
%{C++<br>
#include "nsIInputStream.h"<br>
%}
</div>
<li>Good:
<div class="source-code">
interface nsIInputStream;
</div>
</ul>
<!-- template for future entries
<p>
Rule: <br>
Why:
</p>
<ul>
<li>Bad:
<div class="wrong-source-code">
</div>
<li>Good:
<div class="source-code">
</div>
</ul>
-->
<hr>
<address><a href="mailto:[email protected]">Alec Flett</a></address>
<!-- Created: Wed Sep 4 14:28:25 PDT 2002 -->
<!-- hhmts start -->
Last modified: Wed Sep 4 17:15:00 PDT 2002
<!-- hhmts end -->
</TD>
</TR>
<TR>
<TD COLSPAN="2" ALIGN="RIGHT" VALIGN="TOP">
<div class="documentinfo">
Copyright © 1998-2002 The Mozilla Organization.
<BR>
Last modified September 4, 2002.
<BR>
<A HREF="http://www.mozilla.org/webtools/bonsai/cvslog.cgi?file=mozilla-org/html/projects/xpcom/interface-rules.html&rev=&root=/cvsroot/">Document History</A>.
<BR>
<A HREF="http://doctor.mozilla.org/?file=mozilla-org/html/projects/xpcom/interface-rules.html">Edit this Page</A>.
</div>
</TD>
</TR>
</TABLE>
</BODY>
</HTML>