.. highlight:: none


.. index::
   pair: C language; naming guide
   pair: C language naming; guide

.. _design-guide.impl.c.naming:


C Style -- naming
=================

.. mps:prefix:: guide.impl.c.naming
   pair: C language; naming guide
   pair: C language naming; guide


Introduction
------------

:mps:tag:`scope` This document describes the conventions for naming in C
source code that's internal in the MPS. See design.mps.interface-c_
for the corresponding conventions for the public interface.

.. _design.mps.interface-c: interface-c.html

:mps:tag:`readership` This document is intended for anyone working on or
with the C source code.


Capitalization
--------------

:mps:tag:`capital.macro` Statement-like macros have names consisting of
uppercase words separated by underscores, for example
:c:macro:`ARG_DEFINE_KEY`.

:mps:tag:`capital.constant` Constants have names consisting of a type (named
according to :mps:ref:`.capital.program` or :mps:ref:`.capital.other`), concatenated
with an identifier in uppercase with underscores, for example
``BufferFramePOP_PENDING``.

:mps:tag:`capital.program` Other names with program scope consist of
concatenated title-case words, for example ``BufferFramePush``.

:mps:tag:`capital.other` Other names (including function parameters, names
with block scope, and names with file scope) consist of concatenated
words, the first of which is lowercase and the remainder are
uppercase. For example, ``poolReturn``.


Prefixes
--------

:mps:tag:`prefix.program` Any name with program scope must start with the
name of the module to which it belongs. For example, names belonging
to the buffer module must start with ``buffer`` or :c:type:`Buffer` or
:c:macro:`BUFFER`. Justification: the C language lacks a namespace facility
so the only way to avoid name clashes is for each name to be globally
unique.

:mps:tag:`prefix.file` Any name with file scope should start with the name
of the module to which it belongs. Justification: makes it easy to
tell which module a function belongs to; makes it easy to set
breakpoints in the debugger.


Suffixes
--------

:mps:tag:`suffix.struct` The type of a structure must be the same as the
structure tag, and must consist of the type of the pointer to the
structure concatenated with ``Struct``. For example, :c:type:`ArenaStruct`.

:mps:tag:`suffix.union` The type of a union must be the same as the union
tag, and must consist of the type of the pointer to the union
concatenated with ``Union``. For example, :c:type:`PageUnion`.

:mps:tag:`suffix.class` The type of a class (see design.mps.protocol_)
must end with ``Class``. For example, :c:type:`ArenaClass`.

.. _design.mps.protocol: protocol.html

:mps:tag:`suffix.method` The type of a method in a class must end with
``Method``. For example, :c:type:`PoolFixMethod`.

:mps:tag:`suffix.visitor` The type of a visitor function must end with
``Visitor``. For example, ``TreeVisitor``.

:mps:tag:`suffix.function` The type of other functions must end with
``Function``. For example, :c:type:`TreeKeyFunction`.