Naming convention for eld

[parth-07]

This discussion aims to discuss and decide upon a naming convention for eld. Currently, we do not have a consistent naming convention. Consistent naming convention helps make the code more readable. The primary goals for naming convention for eld are:

• It should be easy to follow. There should not be too many / too strict rules.
• Naming convention should be as close to LLVM as possible.

Current LLVM naming convention:

1. Types: PascalCase and should be a noun
2. Variables: PascalCase and should be a noun
3. Functions: camelCase and should be a verb
4. Additional rules for enum types:
   4.1) Enum should have Kind-like suffix if the enum is used as a discriminator. For example: ValueKind
   4.2) Unscoped enumerators should be prefixed with the enum name / abbreviation.
5. STL-style exceptions
   Functions and classes that are like STL should follow C++ naming convention. (That is, snake_case for almost everything)
6. Macros: All caps

Trying to completely follow LLVM naming convention has been difficult. Let's look at some of the reasons:

• The same naming convention for type and variable names poses unnecessary difficulties. For example, we had a
  type GeneralOptions::AddressMap and corresponding member GeneralOptions::m_AddressMap. With the
  same naming convention, the natural name for both the type and the variable would be AddressMap -- naming conflict.
  There are many more such examples.

• Similar problem happens with parameter and member names in setter-functions.

• PascalCase for variable names seems a bit off for some cases, such as:

auto It = map.find(...); // it seems better in smallcase...
// isReadable seems better. Capitalizing non-important words 
// such as 'Is' seems off for some reason...
bool IsReadable = 0; 

There are a few ways to solve these issues. One way is to use abbreviations for the variable name.
For example, a variable declaration can be AddressMap AM. While this is good for well-known types
such as Module, LinkerConfig and some others, it can make the code less-readable if used for less-known
types such as AddressMap. One of the LLVM guidelines even mentions:

Avoid abbreviations unless they are well known

There have been discussions in LLVM community to change the naming convention for the variable names:
Variable Names Plan — LLVM 21.0.0git documentation,
RFC: changing variable naming rules in LLVM codebase - Project Infrastructure / LLVM Dev List Archives - LLVM Discussion Forums.
A lot of people are in support of changing the naming convention for variable as the current pattern of
Triple TheTriple is a bit redundant.

However, it seems that the variable name change plan did not have enough momentum to go through, in particular,
there were concerns regarding git-blame usability.

Given the LLVM community interest in moving away from PascalCase for variable names, I think we should not proceed
with PascalCase for eld, especially because it is already posing difficulties in adoption.

In the RFC, there are supporters of both camelCase and snake_case for variable names, but it seems that camelCase is more favorable. Some people even mentioned m_ prefix for private/protected members.

I think we can directly follow LLVM naming convention in all cases except the variable names.

I propose the following rules for the eld naming conventions:

• Types: PascalCase and should be a noun
• Variable names: camelCase, or abbreviation for well-known types such as M for Module, LC for LinkerConfig and so on.
• Functions: camelCase and should be a verb
• Additional rules for enum types:
  4.1) Enum should have Kind-like suffix if the enum is used as a discriminator. For example: ValueKind
  4.2) Unscoped enumerators should be prefixed with the enum name / abbreviation.
• STL-style exceptions
  Functions and classes that are like STL should follow C++ naming convention. (That is, snake_case for almost everything)
• Macros: All caps

Please let me know if you have any comments.

If these conventions are okay with everyone, then can we should start enforcing them for the new code that we add.

[quic-areg]

Will we change existing code to conform to this?

[parth-07]

I do not think that we should spend too much efforts in changing the current code to conform to this. A large scale refactoring such as this will make git blame effectively useless :'). We can try adopting to this naming convention for the new code that we add, or the old code that we happen to modify.

[quic-areg]

Any potential refactor can be added to .git-blame-ignore-revs to make it not show up in git blame eg:

# r365730: [Coding style change][lld] Rename variables for non-ELF ports
136d27ab4de0c1d5dedfecc32a9857be78fa0648

# r365595: [Coding style change] Rename variables so that they start with a lowercase letter
3837f4273fcc40cc519035479aefe78e5cbd3055

from the same idea in llvm.

I think this is worth doing as it can be largely automated. We should also change .clang-tidy to conform to the new style