<html>
<head>
  <title>lld: Coding Conventions</title>
</head>
<body>


<h1>
  lld: Coding Conventions
</h1>


<p>The goal is for lld to be eventually accepted by the LLVM community and
become the standard linker used with clang.  Therefore, the lld source
code structure and style is following the 
<a href="http://llvm.org/docs/CodingStandards.html">LLVM Coding Standards</a>
with the exceptions noted below.  The execptions are to solve real world
problems such as disambiguation and avoiding bugs.</p>




<h3>
  <a name="disambiguation">Type name versus non-type name disambiguation</a>
</h3>

<p>Like the LLVM convention, lld uses camel case for names, and capital
letters to begin the name of a type (e.g. <code>Atom</code>, 
<code>Reference</code>).   But, unlike
LLVM the lld convention is to begin non-type identifiers with a lower case 
letter, so they are easily distiguished (e.g. <code>Foo</code> is a type
and <code>foo</code> is a variable).  Here are some concrete examples of
the problem with variables and types being named the same:
</p>
<ul>
        <li>If you see:
            <pre>  Xxx Yyy(Zzz);  // ambiguous LLVM convention</pre>
                Is that a function prototype?  Or a local variable whose object
                constructor takes one argument?<br><br>
                There is no ambiguity with the lld convention because a function 
                prototype would look like:
            <pre>  Xxx yyy(Zzz);  // function prototype in lld convention </pre>
                And a local variable would look like:
            <pre>  Xxx yyy(zzz);  // local object in lld convention </pre>
                <br>
        </li>
        <li>If you see:
                <pre>  Aaa(Bbb)  // ambiguous LLVM convention</pre>
                Is that a function call?  Or casting Bbb to type Aaa?<br><br>
                There is no ambiguity with the lld convention because a function 
                call would look like:
            <pre>  aaa(bbb)  // function call in lld convention </pre>
                And a cast would look like:
            <pre>  Aaa(bbb)  // cast in lld convention </pre>
                <br>
        </li>
        <li>Another problem when types and variables can be named the same is
        that it removes possible variable names because they are already
        taken by type names.  For instance in lld conventions you can name 
        local variables like:
        <pre>   Writer  writer;   // possible only in lld convention
   Atom    atom;     // possible only in lld convention</pre>
        </li>
        <li>Lastly, it is odd that LLVM has a different convention for functions 
        (start with lowercase) and variables (start with uppercase).  They really
        should have the same naming convention because they are interchangeable. 
        For instance you could have:
        <pre>extern void log(const char*);</pre>
        with lots of clients callling it.  Then decide you need to dynamically
        switch the log function, so you change the interface to:
        <pre>extern void (*log)(const char*);</pre>
        And all clients still compile.
        But, according to the LLVM conventions, you need to rename <code>log</code>
        to <code>Log</code> (which means changing all clients) because 
        log is now a variable instead of a function.
        </li>
</ul>
<br>


<h3>
  <a name="ivars">Member variable versus local variable disambiguation</a>
</h3>

<p>Like the LLVM convention, lld uses camel case for variable names. But to
disambiguate data members (aka instance variables, aka ivars) from local (stack)
variables, lld adds a leading underscore to instance variable names 
(e.g. <code>_file</code>, <code>_stringsMaxOffset</code> are ivars). Think
of the leading underbar as short hand for "<code>this-></code>".</p>
<p> It is
important to quickly disambiguate ivars from local variables to understand
the lifetime, scope, and what else might be using the variable.
<ul>
        <li>If you are reading the middle of method in LLVM conventions and see:
        <pre>   Count = <i>expression</i> // ambiguous LLVM convention </pre>
        It is not obvious if Count is a local (stack) variable or an ivar. So you
        don't now if this is a temporary calculated value, or if the value
        will persist (in the object) after this method returns.<br>
        Code using the lld convention makes the variable kind obvious:
        <pre>   _count = <i>expression</i> // ivar assignment, lld  convention
   count  = <i>expression</i> // local var assignment, lld  convention </pre>
        </li>
        <li>When making methods thread safe, it important to guard access to ivars,
        but local (stack) variables do not need guards.  So, again we want to 
        disambiguate the two kinds of variables.
        </li>
        <li>Instance variables and local variables have different lifetimes.  
        Instance variables exist for the life of the object, whereas local variables
        exist just within their scoping (i.e. they are gone when the method
        returns).  Given this, you want to make sure the two kinds of variables
        are initialized and destroy approriately.  Hence disambiguating the
        variable kinds is important when code reviewing. (Yes, there are ways
        like <code>auto_ptr<></code> to help with this.)
        </li>
        <li>Lastly, when ivars and local variables can have the same name, you
        can get accidental shadowing.  Usually this happens when a local variable
        is added which happens to have the same name as an ivar.  Adding that 
        variable could introduce a bug because other uses of that name in the
        method now refer to the local instead of the instance variable. <br>
        A related issue is the naming of constructor parameters.  Often the natural
        name is the same as the ivar name, but this leads to weird shadowing
        warnings and errors.  For instance, you get a warning if you try to 
        compile with -Wshadow, an LLVM style class like:
    <pre> class Foo {  int Flags;   Foo(int Flags) : Flags(Flags) { } };</pre>
        The lld convention does not have these shadowing issues.  The same class
        in lld conventions would be:
        <pre> class Foo {  int _flags;   Foo(int flags) : _flags(flags) { } };</pre>        
        </li>
</ul>


<h3>
  <a name="other">C++ coding conventions of other projects</a>
</h3>
<p>I did some web searching to see what other C++ conventions are documented.
I found no other conventions in which type names and variable names could 
collide as can happen with the LLVM conventions.  Here are some which are 
generally similar (camel case) to LLVM's conventions (e.g. not GNU or unix-like
all lower case conventions).</p>
<ul>
<li><a href="http://www.c-xx.com/ccc/ccc.php">
http://www.c-xx.com/ccc/ccc.php</a>
</li>
<li><a href="http://geosoft.no/development/cppstyle.html#Naming%20Conventions">
http://geosoft.no/development/cppstyle.html
</a>
</li>
<li><a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Variable_Names">
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
</a>
</li>
</ul>





</body>
</html>