head	1.4;
access;
symbols;
locks; strict;
comment	@# @;


1.4
date	99.04.15.15.52.54;	author bkoz;	state dead;
branches;
next	1.3;

1.3
date	99.02.26.18.58.00;	author bkoz;	state Exp;
branches;
next	1.2;

1.2
date	98.10.30.21.18.15;	author ncm;	state Exp;
branches;
next	1.1;

1.1
date	98.07.14.10.40.23;	author ncm;	state Exp;
branches;
next	;


desc
@@


1.4
log
@
1999-04-15   Benjamin Kosnik  <bkoz@@cygnus.com>
	* C++STYLE: Add ChangeLog guidelines for member functions.
	* doc/* : Delete.
	* BADNAMES, BUGS, C++STYLE, CHECKLIST, COPYING,
	DESIGN, HEADER_POLICY, PROBLEMS, RELEASE-NOTES, TODO: Moved into
	docs/text and made less strident.
	* bits/fstream.tcc: Change non-standard ctor to match Sun's sematics.
	* bits/std_fstream.h: Same.
	* src/ios.cc: Same.
	* bits/locfacets.h: Touch.
@
text
@
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 referenced here:

http://www.gnu.ai.mit.edu/prep/standards_toc.html 

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 spontaneously as they gain 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<typename T>
    void 
    template_function(args)
    { }
      -NOT-
  template<class T>
  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<typename _CharT, typename _Traits>
    class basic_ios : public ios_base
    {
    public:
      // Types:
    };
  -NOT-
  template<class _CharT, class _Traits>
  class basic_ios : public ios_base
    {
    public:
      // Types:
    };
  -NOT-
  template<class _CharT, class _Traits>
    class basic_ios : public ios_base
  {
    public:
      // Types:
  };

06. Enumerators
  enum
  {
    space = _ISspace,
    print = _ISprint,
    cntrl = _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 dictate 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 either inline definitions or declarations, keeping to this
     	standard allows all 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 that begin with underscores.  This is called "uglification".
The convention 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.  In particular,
(IMPORTANT!) type and template names should never have a "__" prefix.

--------------------------

[BY EXAMPLE]
    
#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 should 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<typename _Formal_argument>
      void 
      public_template() const throw();

    template<typename _Iterator>
      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-less-standard language features described by lack, not presence:
# ifndef _G_NO_LONGLONG
  extern long long _G_global_with_a_good_long_name;  // avoid globals!
# endif

  // avoid in-class inline definitions, define separately;
  //   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 use "__" in a type name, or
//   within any name; never use "__[0-9]".

#endif /* _HEADER_ */


namespace std {

  template<typename T>  // notice: "typename", not "class", no space
    long_return_value_type<with_many, args>  
    function_name(char* pointer,               // "char *pointer" is wrong.
		  char* argument, 
		  const Reference& ref)
    {
      // int a_local;  /* wrong; see below. */
      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.
  }

}


@


1.3
log
@
1999-02-26  Benjamin Kosnik  <bkoz@@happy.cygnus.com>
	* C++STYLE: Add cases.
	* bits/std_fstream.h: Format.
	* bits/std_streambuf.h: Ditto.
	* bits/std_sstream.h: Ditto.
	* src/basic_file.cc(sys_seek): Fix stack delirium, by keeping
 	return type for _IO_file_seek and __basic_file::seek the same size.
	* bits/basic_file.h: Ditto.
@
text
@@


1.2
log
@
        * bits/basic_string.h: churn definition of npos again.
        * bits/ios.cc: remove #ifdef on ios_base locale member initialization
        * BUGS: clear cruft.
        * C++STYLE: Touchup for release.
        * CHECKLIST: Touchup for release.
        * DESIGN: New file.
        * LICENSE.STD: Add requirement to retain copyrights and to provide
        the license with any copies.
        * README: Update for release.
        * TODO: Minor touchup for release.
	* RELEASE-NOTES: Prepare for release.
@
text
@d2 1
a2 1
C++ Standard Library Style Guidelines  DRAFT 1998-01-23
d5 7
a11 2
This library is written to appropriate C++ coding standards.
Notable differences from what may be previous local practice 
d14 1
d21 2
a22 2
    Reason: In C++, definitions are mixed with executable code.  Here, 
            p is being initialized, not *p.  This is near-universal
d26 1
d34 11
d47 2
a48 1
    template_function(args);
d51 1
a51 1
  void template_function(args);
d59 41
a99 3
  void mangle()
     -NOT-
  void mangle ()  // wrong
d101 33
a133 4
     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.
d182 11
a192 4
    gribble (const gribble&);
    explicit gribble(int __howmany);
    gribble& operator=(const gribble&);
    virtual ~gribble() throw ();
d195 2
a196 1
    inline void  public_member(const char* __arg) const;
d199 5
a203 2
    int one_line() { return 0 }
    int two_lines(const char* arg) 
d205 3
a207 1
    inline int three_lines();  // inline, but defined below.
d211 3
a213 1
      void public_template() const throw();
d215 2
a216 1
      void other_template();
d226 8
a233 2
    enum _Enum { _S_one, _S_two };
    static void _S_initialize_library();
d245 1
a245 1
    { int __local = 0; return __local; }
d262 1
a262 2
namespace std 
{
d265 1
a265 1
    long_return_value_type<with_many,args>  // notice: no spaces in <...>
d269 6
a274 5
  {
    // int a_local;  /* wrong; see below. */
    if (test) { 
	nested code 
    }
d276 1
a276 1
    int a_local = 0;  // declare variable at first use.
d278 9
a286 8
    //  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) {
	// ...
a287 1
  }
d290 1
a290 3
  : _M_private_data(0)
  , _M_more_stuff(0)
  : _M_helper(0);
d300 1
@


1.1
log
@Release preps.
@
text
@d5 3
a7 1
Notable differences from what may be previous local practice include:
d12 2
a13 2
  char *p = "flop";
  char &c = *p;
d20 1
a20 1
  operator== (type)
d22 1
a22 1
  operator == (type)
d25 1
a25 1
            it makes the declaration look like an expression.
d28 2
a29 1
    void template_function(args);
d40 11
d54 3
a56 3
For nonstandard names appearing in Standard headers, we are
constrained to use names that begin with underscores.  The
convention is:
d60 1
a60 1
    Examples:  __count  __ix  __s1
d75 2
a76 1
e.g. _S_top and _M_top.
d80 1
a80 1
type and template names should never have a "__" prefix.
d95 1
a95 1
    gribble () throw ();
d97 3
a99 3
    explicit gribble (int __howmany);
    gribble& operator= (const gribble&);
    virtual ~gribble () throw ();
d102 1
a102 1
    inline void  public_member (const char* __arg) const;
d112 1
a112 1
      void public_template () const throw ();
d114 1
a114 1
      void other_template ();
d122 1
a122 1
    int _M_private_function ();
d125 1
a125 1
    static void _S_initialize_library ();
d136 1
a136 1
  gribble::public_member () const
d164 1
a164 2
    if (test)
      { 
d166 1
a166 1
      }
d176 1
a176 2
    for (unsigned i = 0, mask = 1; mask; ++i, mask <<= 1)
      {
d178 1
a178 1
      }
d181 4
a184 4
  gribble::gribble ()
  : _M_private_data (0)
  , _M_more_stuff (0)
  : _M_helper (0);
@

