C Standard Library Style Guidelines Draft 1999-02-26
-------------------------------------
This Library is Written to Appropriate C Coding Standards. As Such,
IT is intended to precede the recommendations of the gnu coding
Standard, Which Can Be Reference Here:
http://www.gnu.ai.mit.edu/prep/standards_toc.html
Changelog Entries for Member Functions Should Uses
ClassName :: MEMBER FUNCTION NAME SYNTAX As Follows:
1999-04-15 Dennis Ritchie
* SRC / BASIC_FILE.CC (__basic_file :: Open): FIX Thinko in
_G_have_io_file_open bits.
NOTABLE AREAS of Divergence from What May Be Previous Local Practice
(Particularly for GNU C) Include:
01. Pointers and References
Char * p = "flop";
Char & c = * p;
-Not-
Char * p = "flop"; // WRONG
Char & c = * p; // WRONG
Reason: In C , Definitions Are Mixed with Executable Code. Here,
P Is Being Initialized, Not * p. this is near-universal
Practice Among C Programmers; IT IS Normal for C Hackers
To switch spontaneouslyly as the gold experience.
02. Operator Names and ParentheSes
Operator == (TYPE)
-Not-
Operator == (Type) // WRONG
Reason: the == is part of the function name. Separating
It Makes The Declaration Look Like An Expression.
03. Function Names and Parentheses
void mangle ()
-Not-
Void mangle () // WRONG
Reason: No Space Before Parentheses (Except After A Control-Flow
Keyword) Is Near-Universal Practice for C . It Identifies the
Parentheses as the function-call operator or declarator, AS
Opposed to an expression or other overloaded use of parentheses.
04. Template Function Indentation
Template
Template_function (args)
{}
-Not-
Template
Void Template_function (args) {};
Reason: in Class Definitions, WITHOUT INDENTATION Whitespace IS
Needed Both Above and Below The Declaration To Distinguish
IT Visually from Other Members. (Also, Re: "TypenAme"
Rather Than "class".) T OFTEN COULD BE INT, WHICH IS
Not a class. ("Class", Here, IS an anachronism.
05. Template Class Indentation
Template
Class Basic_ios: Public iOS_BASE
{
PUBLIC:
// Types:
}
-Not-
Template
Class Basic_ios: Public iOS_BASE
{
PUBLIC:
// Types:
}
-Not-
Template
Class Basic_ios: Public iOS_BASE
{
PUBLIC:
// Types:
}
06. ENUMERATORS
ENUM
{
Space = _ISSPACE,
Print = _ISPRINT,
CNTRL = _i_ISCNTRL,
}
-Not-
Enum {space = _isspace, print = _isprint, cntrl = _iscntrl};
07. Member Initialization Lists
All one line, Separate from Class Name.
Gribble :: gribble ()
: _M_Private_Data (0), _m_more_stuff (0), _M_HELPER (0);
{}
-Not-
Gribble :: gribble (): _m_private_data (0), _m_more_stuff (0), _M_HELPER (0);
{}
08. TRY / CATCH Blocks
Try {
//
}
Catch (...) {
//
}
-Not-
Try {//} catch (...) {//}
09. Member Functions Declarations and Defintions
Keywords Such As Extern, Static, Export, Explicit, Inline, ETC
Go on the line Above the function name. thus
Virtual Int
Foo ()
-Not-
Virtual int foo ()
Reason: GNU Coding Conventions Dich Return Types for Functions
Are ON A Separate Line Than The Function Name and Parameter List
For definitions. for C , WHERE we have member functions That Can
. Be each Either Inline Definitions or Declarations, Keeping to thisstandard Allows All Me MEMBER FUNCTION NAMES for a Given Class To BE
Aligned to The Same Margin, Increasing Readibility.
10. Invocation of Member Functions with "this->"
For non-uglified names, use this-> name to call the function.
this-> sync ()
-Not-
Sync ()
THE LIBRARY CURRENTLY HAS A MIXTURE OF GNU-C and MODERN C Coding
STYLES. The GNU C Usages Will Be Combed Out Gradually.
Name patterns:
For Nonstandard Names Appearing in Standard Headers, We Are Constrained
To use names. begin with understandcores. This is called "uglification".
The convepen IS:
Local and Argument Names: __ [a-z]. *
EXAMPLES: __COUNT __IX __S1
TYPE NAMES AND TEMPLATE FORMAL-Argument Names: _ [a-z] [^ _]. *
Examples: _helper _chart _n
MEMBER DATA AND FUNCTION NAMES: _M _. *
Examples: _m_num_elements _m_initialize ()
Static Data Members, Constants, And Enumerations: _S_. *
Examples: _S_max_elements _s_default_value
Don't Use names in The Same Scope That Differ Only In The Prefix,
E.G. _S_top and _m_top. See Badnames for A List of Forbidden Names.
(The Most Tempting of these Seem to be and "_t" and "__sz".)
Names Must Never Have "__" internally; it Would Confuse Name
Unmanglers on some targets. Also, Never USE "__ [0-9]", Same Reason.
----------------------------
[By esample]
#ifndef _header_
#define _Header_ 1
Namespace STD
{
Class Gribble
{
PUBLIC:
// ctor, op =, DTOR
Gribble () throw ();
Gribble (Const gribble);
Explicit
Gribble (int __howmany);
Gribble &
Operator = (const gribble);
Virtual
~ gribble () throw ();
// argument
Inline void
Public_member (const char * __ARG) const; // in-class function definitions surnted be restricted to one-liners.
int
One_line () {return 0}
int
Two_Lines (Const Char * Arg)
{RETURN STRCHR (arg, 'a');}
Inline int
Three_Lines (); // inline, but defined Below.
// Note Indentation
Template
Void
Public_Template () Const throw ();
Template
Void
Other_Template ();
Private:
Class_helper;
INT _M_PRIVATE_DATA;
INT _M_MORE_STUFF;
_HELPER * _M_HELPER;
INT _M_PRIVATE_FUNCTION ();
ENUM _ENUM
{
_S_ONE,
_S_TWO
}
Static void
_S_initialize_library ();
}
// more-or-legs-standard Language Features Described by lats, not present:
# iFNDef_g_no_longlong
EXTERN Long Long_G_Global_with_a_good_long_name; // Avoid Globals!
# Endif
// Avoid in-class inline definitions, define separationLy;
// Likewise for Member Class Definitions:
Inline int
Gribble :: public_member () const
{INT __LOCAL = 0; return__local;}
Class Gribble :: _ Helper
{
INT_M_STUFF;
Friend Class Gribble;
}
}
// Names Beginning with "__": ONLY for arguments and
// local variables; never us "__" in a type name, or
// within any name; never us "__ [0-9]".
#ENDIF / * _HEADER_ * /
Namespace std {
Template
Long_return_Value_type
Function_name (Char * Pointer, // "char * pointer" is Wrong.
Char * argument,
Const Reference & Ree
{
// int a_local; / * wrong; see bebelow. * /
IF (Test)
{
Nested code
}
INT A_LOCAL = 0; // Declare Variable At First USE.
// CHAR A, B, * P; / * WRONG * /
CHAR A = 'a';
Char b = a 1; char * c = "abc"; // Each Variable Goes on Its OWN LINE, Always.
// Except Maybe Here ...
For (unsigned i = 0, mask = 1; mask; i, mask << = 1) {
// ...
}
}
Gribble :: gribble ()
: _M_Private_Data (0), _m_more_stuff (0), _M_HELPER (0);
{}
Inline int
Gribble :: Three_Lines ()
{
// Doesn't Fit in One Line.
}
}
