lld: Coding Conventions

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 LLVM Coding Standards with the exceptions noted below. The execptions are to solve real world problems such as disambiguation and avoiding bugs.

Type name versus non-type name disambiguation

Like the LLVM convention, lld uses camel case for names, and capital letters to begin the name of a type (e.g. Atom, Reference). But, unlike LLVM the lld convention is to begin non-type identifiers with a lower case letter, so they are easily distiguished (e.g. Foo is a type and foo is a variable). Here are some concrete examples of the problem with variables and types being named the same:

If you see:
```
  Xxx Yyy(Zzz);  // ambiguous LLVM convention
```
Is that a function prototype? Or a local variable whose object constructor takes one argument?

There is no ambiguity with the lld convention because a function prototype would look like:
```
  Xxx yyy(Zzz);  // function prototype in lld convention 
```
And a local variable would look like:
```
  Xxx yyy(zzz);  // local object in lld convention 
```
If you see:
```
  Aaa(Bbb)  // ambiguous LLVM convention
```
Is that a function call? Or casting Bbb to type Aaa?

There is no ambiguity with the lld convention because a function call would look like:
```
  aaa(bbb)  // function call in lld convention 
```
And a cast would look like:
```
  Aaa(bbb)  // cast in lld convention 
```
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:
```
   Writer  writer;   // possible only in lld convention
   Atom    atom;     // possible only in lld convention
```
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:
```
extern void log(const char*);
```
with lots of clients callling it. Then decide you need to dynamically switch the log function, so you change the interface to:
```
extern void (*log)(const char*);
```
And all clients still compile. But, according to the LLVM conventions, you need to rename log to Log (which means changing all clients) because log is now a variable instead of a function.

Member variable versus local variable disambiguation

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. _file, _stringsMaxOffset are ivars). Think of the leading underbar as short hand for "this->".

It is important to quickly disambiguate ivars from local variables to understand the lifetime, scope, and what else might be using the variable.

If you are reading the middle of method in LLVM conventions and see:
```
   Count = expression // ambiguous LLVM convention 
```
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.
Code using the lld convention makes the variable kind obvious:
```
   _count = expression // ivar assignment, lld  convention
   count  = expression // local var assignment, lld  convention 
```
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.
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 auto_ptr<> to help with this.)
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.
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:
```
 class Foo {  int Flags;   Foo(int Flags) : Flags(Flags) { } };
```
The lld convention does not have these shadowing issues. The same class in lld conventions would be:
```
 class Foo {  int _flags;   Foo(int flags) : _flags(flags) { } };
```

C++ coding conventions of other projects

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).