<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). It makes sense to have variables and
functions named the same way because they are both "things with an address at
runtime".
</p>
<p>On the other hand, it is confusing that LLVM convention for variable names
is the same as for type names, instead of like other runtime objects (functions).
</p>
<p>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, lambdas highlight the confusion LLVM variable naming convention.
How to name a lambda? The act like both variables and functions. For example:
<pre>
auto myLamda = [&] (int x) -> int { return x+1; } // lld convention
</pre>
</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>unique_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) { } }; // LLVM convention triggers -Wshadow warning</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) { } }; // lld convention has no warning</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>