Coding Standards and Conventions

File Names and Organization

• Naming conventions allow searching and navigation across files
  Example C header files
• Style guides specify how elements are ordered within a file
  Java example:
  1. class variables
  2. instance variables
  3. constructors
  4. methods
  and
  1. Private
  2. Protected
  3. Public

Common File Names

Common File Extensions

Indentation

• Will help identify blocks
• Beware of difference between tab character and spaces
• Correct settings in editor/IDE important
      void linkTable(Table t) throws SQLException {
      String name = t.getName();
  
      for (int i = 0; i < tTable.size(); i++) {
          Table o = (Table) tTable.elementAt(i);
  
          if (o.getName().equals(name)) {
          throw Trace.error(Trace.TABLE_ALREADY_EXISTS, name);
          }
      }
  
• Non-standard values often appear as editor commands:
  /*
   * Local Variables:
   * tab-width: 4
   * c-indent-level: 4
   * c-argdecl-indent: 4
   * c-continued-statement-offset: 4
   * c-continued-brace-offset: -4
   * c-label-offset: -4
   * c-brace-offset: 0
   * End:
   */
  
• Interpreting indentation can save you from counting brackets:
          if ((u_int)fd >= fdp->fd_nfiles ||
              (fp = fdp->fd_ofiles[fd]) == NULL)
                  return (EBADF);
  

Formatting

• Two main schools:
  • Opening brace on separate line (GNU, Linux, Windows):
        if (ia->ia_maddr != MADDRUNK)
        {
            sc->pPacketPagePhys = ia->ia_maddr;
        }
    
  • Opening brace on same line (BSD Java)
        if ((cp = strchr(*argv, ':')) != NULL) {
            *cp++ = '\0';
            a_gid(cp);
        }
    
• Both are OK
• Inconsitency is a problem
  xpupil.y = Xy(w->eyes.pupil[0].x, w->eyes.pupil[0].y, &w->eyes.t);
  xnewpupil.x =  Xx(newpupil[0].x, newpupil[0].y, &w->eyes.t);
  xnewpupil.y =  Xy(newpupil[0].x, newpupil[0].y, &w->eyes.t);
  if (!XPointEqual (xpupil, xnewpupil)) {
  
• Why? All explanations spell trouble:
  • Undisciplined programmer
  • Haphazard integration
  • Uncoordinated team

Comments

• The /*- sequence means "Don't format"
• Java /** comments are read by javadoc
• FALTRHOUGH comments mark continued case statements:
      case 10:                /* yy */
          lt->tm_year = ATOI2(p);
          if (lt->tm_year < 69)       /* hack for 2000 ;-} */
              lt->tm_year += 100;
          /* FALLTHROUGH */
      case 8:                 /* mm */
          lt->tm_mon = ATOI2(p);
  
• NOTREACHED mark non-reachable code points
  size_t
  strcspn(const char *s1, const char *s2)
  {
      register const char *p, *spanp;
      register char c, sc;
  
      /*
       * Stop as soon as we find any character from s2.  Note 
       * that there must be a NUL in s2; it suffices to stop 
       * when we find that, too.
       */
      for (p = s1;;) {
          c = *p++;
          spanp = s2;
          do {
              if ((sc = *spanp++) == c)
                  return (p - 1 - s1);
          } while (sc != 0);
      }
      /* NOTREACHED */
  }
  
• $Identifier$ sequences are expanded by the VCS
• XXX means something is probably wrong here
• TODO marks areas of further work
• FIXME marks areas of further enhancement

Naming Convention Styles

1. Capitalization, or CamelCase. Examples:
   • SetErrorMode (Win32)
   • RandomAccessFile (Java)
2. Underscore separation (exponent_is_negative) (GNU)
3. Initials (splbio : set processor level for buffered I/O); also removal of vowels and word endings (strcmp)

Java Naming Conventions

• Package names start with a domain identifier (org, com)
• Class and interface names start with an uppercase character
• Variable, field, and method names start with a lowercase character

• Library.register(hAlias)
• name.equals(".c")

Hungarian Notation

• Developed by Charles Symonyi
• Prevalent in Win32 code
• Composed by the sequence
  1. Tag (indicates type)
  2. Base name (distinguishes identifiers with same type)
  3. Qualifier (standard differentiators)
• Often abused to encode hardware-dependent types (e.g. WORD)

Primitive Types

Type Constructions

Name Qualifiers

VB Primitive Types

VB Common Controls

Programming Practices

Examples:

• Use getopt to parse command line arguments.
  Standard:
      while ((ch = getopt(argc, argv, "mo:ps:tx")) != -1)
          switch(ch) {
          [...]
          case 'x':
              if (!domd5)
                  requiremd5("-x");
              MDTestSuite();
              nomd5stdin = 1;
              break;
          case '?':
          default:
              usage();
          }
      argc -= optind;
      argv += optind;
  
  Deviation:
      while (argc > 1 && argv[1][0] == '-') {
          switch(argv[1][1]) {
          [...]
          case 's':
              sflag = 1;
              break;
          default:
              usage();
          }
          argc--; argv++;
      }
      nfiles = argc - 1;
  
• Declare structures together with a typedef (Win32).
  typedef struct _OVERLAPPED {
      DWORD   Internal;
      DWORD   InternalHigh;
      DWORD   Offset;
      DWORD   OffsetHigh;
      HANDLE  hEvent;
  } OVERLAPPED, *LPOVERLAPPED;
  
• Assume 32-bit (nowadays 64-bit) address space and virtual memory (GNU)
• Use STL containers (modern C++ software)

Process Standards

• Standard documents (e.g. manual page, texinfo, javadoc)
• Build process (tools and macros)
• Release process
  • Distribution format and files
  • Installer files
  • Versioning and tagging
  • Installation directories
  • User configuration options
• Often enforced through automation

Further Reading

• L. W. Cannon, R. A. Elliott, L. W. Kirchhoff, J. H. Miller, J. M. Milner, R. W. Mitze, E. P. Schan, N. O. Whittington, Henry Spencer, David Keppel, and Mark Brader. Recommended C style and coding standards. Available online http://sunland.gsfc.nasa.gov/info/cstyle.html (December 2001). Updated version of the Indian Hill C Style and Coding Standards paper.

• The FreeBSD Project. Style—Kernel Source File Style Guide, December 1995. FreeBSD Kernel Developer's Manual: style(9). Available online at http://www.freebsd.org (March 2003).

• Brian W. Kernighan and Rob Pike. The Practice of Programming. Addison-Wesley, Reading, MA, 1999.

• Brian W. Kernighan and P. J. Plauger. The Elements of Programming Style. McGraw-Hill, New York, second edition, 1978.

• Charles Simonyi. Meta-programming: a Software Production Method. PhD thesis, Stanford University, CA, December 1976. Online http://www.parc.xerox.com/publications/bw-ps-gz/csl76-7.ps.gz (December 2001).

• Charles Simonyi. Hungarian notation. Available online http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvsgen/html/hunganotat.asp (December 2001), November 1999. Microsoft Developer Network Library.

• Henry Spencer and Geoff Collyer. #ifdef considered harmful or portability experience with C news. In Rick Adams, editor, USENIX Conference Proceedings, pages 185–198, Berkeley, CA, Summer 1992. USENIX Association.

• Henry Spencer. How to steal code—or—inventing the wheel only once. In USENIX Conference Proceedings, pages 335–345, Berkeley, CA, Winter 1988. USENIX Association.

• Henry Spencer. The Ten Commandments for C programmers (annotated edition). ;login:, 18(2):29–31, March slash April 1993.

• Diomidis Spinellis. Code Reading: The Open Source Perspective, pages 225–240. Effective Software Development Series. Addison-Wesley, Boston, MA, 2003.

• Diomidis Spinellis. Job security. IEEE Software, 26(5):14–15, Sep/Oct 2009. (doi:10.1109/MS.2009.131 (http://dx.doi.org/10.1109/MS.2009.131))

• Diomidis Spinellis. elyts edoc. IEEE Software, 28(2):104–103, March/April 2011. (doi:10.1109/MS.2011.31 (http://dx.doi.org/10.1109/MS.2011.31))

• Richard Stallman et al. GNU coding standards. Available online http://www.gnu.org/prep/standards_toc.html (December 2001), October 2001.

• Sun Microsystems, Inc. Java code conventions (http://java.sun.com/docs/codeconv/). Available online http://java.sun.com/docs/codeconv/ (December 2001), April 1999.

Exercises and Discussion Topics

1. Identify the coding standards that apply in your organization. In the form of a table, compare their coverage against two other commonly used standards.
2. Discuss the advantages and disadvantages of defining and declaring code elements in a strictly prescribed order. How do modern integrated development environments affect your view?
3. Devise a guideline that prescribes under what circumstances the formatting of an imported piece of code should be changed to conform to the local coding standards. Take into account code quality, readability, maintenance, revision control, and future integration issues.
4. Some argue that the Hungarian naming conventions duplicate work that is performed by a type checking compiler. Discuss.
5. Create an itemized list of programming practices that can help code readability. Try, where possible, to reference existing examples.
6. Identify the process standards that apply in your organization. Explain what software elements (files, directories) have to be examined in order to verify the conformance of a system against those standards.

• Contents

 Last change: Wednesday, June 6, 2012 4:02 pm
 Unless otherwise expressly stated, all original material on this page created by Diomidis Spinellis is licensed under a Creative Commons Attribution-Share Alike 3.0 Greece License.