Common Mistakes and Legacy Patterns#
LLVM-libc’s conventions have changed over the years, and the tree still contains code written to older ones. Existing code is not precedent. A pattern being present in the tree, even many times, does not make it acceptable in a new change. This page lists the mistakes reviewers see most often and the old patterns that should not be copied.
This applies with particular force to changes written with AI assistance, because a tool that imitates nearby code will imitate its outdated parts too.
Larger areas of the tree that are known to need rework are listed in
Roadmap and Known Issues. Do not model new code on them. Issues for LLVM-libc are filed
under the libc label in the
issue tracker.
Most common mistakes#
Calling one entrypoint from another. It is the natural way to write many functions and it is not allowed. Some existing code does it; that code is to be cleaned up and is not an example to follow. See Entrypoints do not call entrypoints.
Mimicking another libc’s interface. Changing a type’s layout, a function’s observable behavior, or the set of exported symbols solely to match another libc is sometimes the quickest way to get an existing program running. That matching is not the intent for LLVM-libc, and goes against its design principles. See: Making existing software work.
Copying an outdated pattern from old code. See the table below.
Copying or translating code from another libc. Neither is allowed. Original implementations only states where the line is between learning from another implementation and taking from it.
Leaving out part of the registration. A new function needs an entry in
libc/include/<header>.yamland in the relevantentrypoints.txtfiles in addition to its implementation. A new public type needs its own registration as well. See Implementing a New Function.
Legacy patterns#
Seen in the tree |
Write this instead |
|---|---|
A first line of the form |
The current LLVM file header, shown in Implementation Guidelines. Update the header of any file you touch. |
|
A wrapper in |
Functions and variables inside an anonymous namespace |
|
A |
Include what you use: each file includes the proxy header for every type and macro it names. |
|
The proxy headers in |
|
The helper returns |
A new file or directory named |
A name that says what the code does. |
|
|
A bare path literal such as |
|
Code that is hard to review#
These are not style violations in the formatting sense. They make code hard to reason about, and reviewers will ask for them to be rewritten.
Deeply nested control flow. An
ifinside a loop inside a loop inside anifis difficult to follow. Collapse conditions, return early, and move inner blocks into helper functions.while (true)where the exit test is the first or last statement of the body. That test is the loop condition. Write it as awhileordo/whilecondition. The same applies to a body that ends inif (x) continue; else return;. A loop whose exit test is in the middle of the body is a different case, andwhile (true)with abreakis a reasonable way to write it.Lambdas used as local helper functions. A lambda that captures local variables has inputs that do not appear at the call site, so the call no longer shows what the helper reads or changes. If the code is only being factored out for reuse or readability, write a
staticfunction and pass what it needs explicitly. A short lambda that is passed to another function as a callable is fine.Templates that accept more than the code supports. A function template whose body only works for subclasses of one class, or for callables with one signature, should say so in its declaration, so that the compiler rejects an argument that makes no sense. Take the base class by reference, or take a
cpp::function_refwith the expected signature, instead of an unconstrainedtypename T. Where a template is needed, constrain it, for example withcpp::enable_if_tor astatic_assert. Overloading a function for the specific types it supports is fine, and so is a template that is generic on purpose. The same applies to variadic argument forwarding.Magic constants. A bare
7,61, or0xFFFin an expression leaves the reader to work out what it stands for. Give every such constant a name that says what it means. Multiplying byDAYS_PER_WEEKexplains itself; multiplying by7does not.