Inid Coding Style Guide.  (2000-05-13)


This file specifies the preferred style for the core part of inid source code.
Contributors MUST follow the style for adding to and modifying source files
in the main trunk of developing.



[Scope of This Document]

- Only for the core part of inid, that is, inid/*.{cc,h} and inid/POSIX/**.
  Neither inid/Windows/ nor other parts that will appear in the future are
  out of scope.

- Only for the main trunk.
  Contributors may create branches for experimental codes, where no duty
  to conform to this document; contributors, however, should conform to
  the document even in such cases in preparation for the future merge of
  source code trees.



[Class Design]

- Information objects, typically derived from class ActiveObject, have
  their special object model. Especially, method calls and reading/writing
  of member variables are not allowed.



[Language Constructs]

- DO NOT USE TEMPLATE, EXCEPTION NOR NAMESPACE.

- DO NOT USE C++ STANDARD LIBRARY.  C libraries are only available.

- DO NOT USE RTTI (run-time type information), except for debugging use.

- DO NOT USE C++ STYLE CAST EXPRESSION.  // const_cast, static_cast, T(expr)
  C-style cast is only available.        // (T)expr

These restrictions are for portability. New language features nor new
libraries are not available in many practical environments up to the present.


- POSIX functions are preferred to old SysV/BSD functions.

- Goto statement is available only in a few restricted contexts:
  = multi-level break,
  = multi-level continue,
  = alternative for tail-recursion, and
  = handling error recovery.



[Indent, Spaces and Braces]

- DO NOT USE BOTH GNU STYLE NOR WINDOWS STYLE.


- Indentation is an 8 character hard tab (^I).
  Do not assume, in addition, readers always deal with tabs as 8 columns
  spaces; that is, do not use hard tabs within a line to justify columns.

- Second level indents are 2 spaces.

- Maximum width of source files are 80 columns.

       |[--^I--]if (!getnameinfo(res->ai_addr, res->ai_addrlen,
       |[--^I--]  hbuf, sizeof(hbuf), sbuf, sizeof(sbuf),
       |[--^I--]  NI_NUMERICHOST|NI_NUMERICSERV)) {
       |[--^I--][--^I--]AcceptorReactor::PacketUnregisterAcceptor *pkt =
       |[--^I--][--^I--]  new AcceptorReactor::PacketUnregisterAcceptor;
       |[--^I--]}

       |Stdcode::CharsetTableInitEntry
       |  Stdcode::CharsetTable::init_table[] = {
       |[--^I--]// first class table
       |[--^I--]{ ct_94,  'B', { 1, 1, 0, cs_ASCII      } },
       |[--^I--]{ ct_94N, 'B', { 2, 2, 1, cs_JISX0208   } },
       |[--^I--]{ ct_96,  'A', { 1, 1, 0, cs_ISO8859_1  } },
       |[--^I--]// unification table
       |[--^I--]{ ct_94,  '@', { 1, 1, 0, cs_ASCII      } },
       |[--^I--]{ ct_94,  'A', { 1, 1, 0, cs_ASCII      } }
       |};

For readability, hard tabs are simply shown as 8 spaces in the following
part of this document.


- Comma characters in function-call arguments are followed by a space.
- Function names and macro names are not followed by any spaces.
- Just inside of parenthesis-es does not contain any spaces.
- Expressions terminated with semicolons are not followed by any spaces.

       |        i = strtol((argc--, argv++), &ep, 10);
       |        maxi = MAX(i, maxi);

- Expressions may contain proper number of single space characters with
  considerations of readability. Both too many and too few are not good.
  Insertion of spaces should reflect a relation and meaning of subexpressions.

       |        static char name1[] = "IPv6Acceptor ";
       |        static char name2[] = "/TCP";
       |        l = sizeof(name1)-1 + strlen(listenport) + sizeof(name2)-1;
       |        myname = new CountedStr(MallocBlock::allocate(l+1), l);

- IF statements are as follows. "if" is followed by a space.
  The "else" clause must be with 2 brace sections, one for then-clause and
  another for else-clause, and then-clause is not followed by any spaces.

       |        fp = fopen("filename.txt", "r");
       |        if (fp != NULL) {
       |                do_process(fp);
       |                fclose(fp);
       |        }else {
       |                perror("sample");
       |        }

  The following style is also acceptable.

       |        if (isactive(userdb)) userdb->shutdown();

  The following style is NOT SO GOOD in most context.

       |        if (isactive(userdb))
       |                userdb->shutdown();

  All of the followings are NOT ACCEPTABLE.

       |        if (condition)
       |        {                        /* not acceptable */
       |                statement;
       |        }

       |        if (condition)
       |                statement;        /* not acceptable */
       |        else {
       |                ...
       |        }

- WHILE statements are as follows. "while" is followed by a space.

       |        while (condition) {
       |                statement;
       |        }

       |        while (condition) statement;

  The following style is NOT SO GOOD in most context.

       |        while (condition);
  
  All of the followings are NOT ACCEPTABLE.

       |        while (condition)
       |        {                        /* not acceptable */
       |                statement;
       |        }

       |        while (condition)
       |                statement;        /* not acceptable */

- DO-WHILE statements are as follows. "do" is followed by a space.
  Both a right brace and "while" keyword must be within a same line.

       |        do {
       |                statement;
       |        }while (condition);

- FOR statements are as follows. "for" is followed by a space.

       |        for (l=0; l<max; l++) {
       |                statement;
       |        }

       |        count = 0;
       |        for (p=q.first(); !p.isempty(); p=p->next()) count++;

- Infinite loop is as follows.

       |        for(EVER) {                /* The author prefers it:-) */
       |                statement;
       |        }

       |        for (;;) {
       |                statement;
       |        }

       |        while (1) {
       |                statement;
       |        }

- RETURN statement is as follows. "return" is not followed by a parenthesis.

       |        return;

       |        return dstr.length() - 1;

- Function definitions are as follows.
  Function name is started at the top of the line.
  The left brace is also at the top of the line.

       |char *
       |get_dirname_from_pathname(const char *path, int extra_space)
       |{
       |        int len;
       |        char *rp;
       |
       |        len = strlen(path);
       |        rp = (char *)MallocBlock::allocate(len + 1 + extra_space);
       |        strcpy(rp, path);
       |        rp[len-1] = 0;
       |        return rp;
       |}

  Static member functions follow the comment "//static".

       |//static
       |void
       |ClientPort::shutdownSystem()
       |{
       |        if (pkt_reschedule != NULL) {
       |                pkt_reschedule->detach();
       |        }
       |}



[Naming Convention]

- DO NOT USE HUNGARIAN NOTATION.


- Class names are expressed in /[A-Z][A-Za-z0-9]*/, such as PacketReschedule,
  IPv6Acceptor and UserClientDriver.

- Both function names and variable names are expressed in /[a-z][A-Za-z0-9_]*/.
  Words are separated by '_' or an upper case alphabet.

- Constant macro names and enumeration item names both are expressed in
  /[A-Z][A-Za-z0-9_]*/.  If the names have semantics of traditional constants,
  in particular, the names are in /[A-Z0-9_]*/.



[Notes]

This guide is *partly* based on the 4.4BSD coding style guide.

This document will be updated at any time.

Not all of existing codes are conformed to this document.
They should be rewritten.