mirror of
https://github.com/c64scene-ar/llvm-6502.git
synced 2024-08-23 02:29:18 +00:00
restructure this for readability, correct the example to follow the public ivar name convention
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@121443 91177308-0d34-0410-b5e6-96231b3b80d8
This commit is contained in:
parent
2ea8ee7c76
commit
69ad797214
@ -814,32 +814,46 @@ locality.</p>
|
||||
</div>
|
||||
|
||||
<div class="doc_text">
|
||||
<p>Poorly-chosen names mislead the reader and cause bugs. We cannot
|
||||
<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot
|
||||
stress enough how important it is to use <em>descriptive</em> names.
|
||||
Pick names that match the semantics and role of the underlying
|
||||
entities, within reason. Avoid abbreviations unless they are well
|
||||
known.</p>
|
||||
known. After picking a good name, make sure to use consistent capitalization
|
||||
for the name, as inconsistency requires clients to either memorize the APIs or
|
||||
to look it up to find the exact spelling.
|
||||
</p>
|
||||
|
||||
<p>In general, names of types, functions, variables, and enumerators
|
||||
should be in camel case (e.g. <tt>TextFileReader</tt>
|
||||
and <tt>isLValue()</tt>). Type names (including classes, structs,
|
||||
enums, typedefs, etc) should be nouns and start with an upper-case
|
||||
letter (e.g. <tt>TextFileReader</tt>). An <tt>enum</tt> for all the
|
||||
different kinds of something should be named with the <tt>Kind</tt>
|
||||
suffix. Function names should be verb phrases (as they represent
|
||||
actions) and start with a lower-case letter (e.g. a predicate may be
|
||||
named <tt>isFoo()</tt> or <tt>hasBar()</tt>, while the name of a
|
||||
command-like function should be imperative,
|
||||
like <tt>openFile()</tt>).</p>
|
||||
<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt>
|
||||
and <tt>isLValue()</tt>). Different kinds of declarations have different rules:
|
||||
</p>
|
||||
|
||||
<p>Enumerators and public member variables should start with an
|
||||
upper-case letter, just like types. Unless the enumerators are
|
||||
defined in their own small namespace or inside a class, they should
|
||||
have a prefix. For example, <tt>enum ValueKind { ... };</tt> may
|
||||
contain enumerators like
|
||||
<tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc. Enumerators that
|
||||
are just convenience constants are exempt from the requirement for a
|
||||
prefix. For instance:</p>
|
||||
<ul>
|
||||
<li><b>Type names</b> (including classes, structs, enums, typedefs, etc) should
|
||||
be nouns and start with an upper-case letter (e.g. <tt>TextFileReader</tt>).
|
||||
</li>
|
||||
|
||||
<li><b>Function names</b> should be verb phrases (as they represent
|
||||
actions), and command-like function should be imperative. The name should
|
||||
be camel case, and start with a lower case letter (e.g. <tt>openFile()</tt>
|
||||
or <tt>isFoo()</tt>).
|
||||
</li>
|
||||
|
||||
<li><b>Enum declarations</b> (e.g. "enum Foo {...}") are types, so they should
|
||||
follow the naming conventions for types. A common use for enums is as a
|
||||
discriminator for a union, or an indicator of a subclass. When an enum is
|
||||
used for something like this, it should have a "Kind" suffix (e.g.
|
||||
"ValueKind").
|
||||
</li>
|
||||
|
||||
<li><b>Enumerators</b> (e.g. enum { Foo, Bar }) and
|
||||
<b>public member variables</b> should start with an upper-case letter, just
|
||||
like types. Unless the enumerators are defined in their own small
|
||||
namespace or inside a class, enumerators should have a prefix corresponding
|
||||
to the enum declaration name. For example, <tt>enum ValueKind { ... };</tt>
|
||||
may contain enumerators like <tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>,
|
||||
etc. Enumerators that are just convenience constants are exempt from the
|
||||
requirement for a prefix. For instance:</p>
|
||||
|
||||
<div class="doc_code">
|
||||
<pre>
|
||||
enum {
|
||||
@ -849,6 +863,10 @@ enum {
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<p>As an exception, classes that mimic STL classes can have member names
|
||||
in STL's style of lower-case words separated by underscores
|
||||
(e.g. <tt>begin()</tt>, <tt>push_back()</tt>, and <tt>empty()</tt>).</p>
|
||||
@ -858,16 +876,16 @@ in STL's style of lower-case words separated by underscores
|
||||
<pre>
|
||||
class VehicleMaker {
|
||||
...
|
||||
Factory<Tire> f; // Bad -- abbreviation and non-descriptive.
|
||||
Factory<Tire> factory; // Better.
|
||||
Factory<Tire> tireFactory; // Even better -- if VehicleMaker has more than one
|
||||
Factory<Tire> F; // Bad -- abbreviation and non-descriptive.
|
||||
Factory<Tire> Factory; // Better.
|
||||
Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one
|
||||
// kind of factories.
|
||||
};
|
||||
|
||||
Vehicle MakeVehicle(VehicleType Type) {
|
||||
VehicleMaker m; // Might be OK if having a short life-span.
|
||||
Tire tmp1 = m.makeTire(); // Bad -- 'tmp1' provides no information.
|
||||
Light headlight = m.makeLight("head"); // Good -- descriptive.
|
||||
VehicleMaker M; // Might be OK if having a short life-span.
|
||||
Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information.
|
||||
Light headlight = M.makeLight("head"); // Good -- descriptive.
|
||||
...
|
||||
}
|
||||
</pre>
|
||||
|
Loading…
Reference in New Issue
Block a user