Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Source Code Style Guide

The names of variables, functions, and object classes in VMD follow certain conventions in their capitalization and syntax. Also, the files used for VMD code, documentation, and data are formatted according to specific guidelines. This section describes these style guidelines.

Source code formatting conventions

A primary factor in the correct formatting of VMD source code is that it be easily readable by others, years after being written. Compact coding styles are nice, as long as they are readable. Here are several guidelines to follow when modifying or adding code to VMD:

Naming conventions

Most of the naming practices employed within the VMD source tree are based on a few common sense principles: The remaining guidelines provide further suggestions for correctly naming classes, functions, variables, and so on.

Class names

Names of C++ classes should begin with a capital letter, and not contain any underscores. Class names comprised of multiple words should have each word capitalized. Example: DisplayDevice

Classes derived from a base class should generally append a descriptive word to the base class name. If the new word begins with a number, the additional word should be added to the end of the base class name. Examples: GraphicsFltkRepDynamicBonds and Displayable3D

Class member variable names

Names of variables which are members of C++ classes follow the same formatting rules as names of classes, except variable names should begin with a lower case letter. Quite often, if the variable is an instance of a particular class, the name of the variable is identical to the class name but with a lower case initial letter.

Class member function names

Names of functions which are members of C++ classes should be in all lower case letters, and use underscores to separate distinct words in their names. Example:
  void Scene::prepare_draw(DisplayDevice * d)

Global variable names

Don't even think about adding global variables, they are the enemy! That being said, global variables should be marked with XXX and commented profusely. The names of global variables in VMD follow the same rules as for variables which are members of a particular class. It is recommended to use the following suggestions when naming a global variable:
  1. Choose a single-word name, and use all lower case.
  2. Prepend "vmdglobal" to the variable name, to make it obvious, and hopefully inconvenient to type. *grin*
  3. If it is assured there should be only one instance of a particular class, and the instance should be global, choose a name identical to the base class of the variable but with the first letter in lower case.
Examples: vmdglobalscene and vmdglobalmoleculeList

Global function names

Global functions, which are found mainly in hash.c, utilities.C, vmdsock.c, vmddlopen.c, VMDDir.C, and VMDThreads.C follow one or more of the following rules:
  1. Functions contain all lower case letters, and either contain no underscores at all, or contain underscores to separate words.
  2. Portability wrapper functions that emulate standard APIs are named by prepending some string containing "vmd" to function names, such as vmdsock_write, vmddlopen, and vmd_opendir.
Examples: hash_lookup(), time_of_day(), vmd_thread_numprocessors(), and VMDinitUI(),

Preprocessor macro names

Names of C/C++ preprocessor macros should be written entirely in capital letters. Portabbility macros which emulate a standard system-provided macro should prepend VMD so that the macro doesn't interfere with system includes or third-party library headers, etc. Preprocessor macros which enable or disable some VMD feature at compilation time should be descriptively named macros containing no underscores and should only be used as true/false flags. Examples: VMD_MAX_CLIP_PLANE, VMDUSEOPENGLSHADER

Source code file names

Each C++ class, except for very small classes used by only a small number of other classes, should be placed in a separate .h file, and if necessary a .C file as well. The base name of the files for the class should be identical to the class name itself. Examples:
 DisplayDevice.h and DisplayDevice.C
 NameList.h (no NameList.C needed)

C source code files should have a .c extension (that is, use a lower case c), while C++ files should have a .C extension. ALL header files should have a .h extension, and any Fortran files should have a .f extension. Latex files should end in .tex.

Documentation file names

Documentation files, which are in Latex format, all contain a .tex or .dox extension and begin with a prefix of one of the following: vmd, ig, pg, or ug. Files with a vmd prefix are used by several Guides; files with the remaining prefixes are used only by that particular Guide. For all files except the main driver Latex files for the Guides and the Book, the filenames contain an underscore after the prefix and a concluding descriptive word. No capital letters are used. Examples:
  vmd_macros.tex
  pg_chapters.tex
  ug.tex

Creating new files

When new files are to be added to VMD, for any of the different subdirectories, the following steps should be followed:

  1. Once an initial version of the file is ready, it must be formatted properly to conform to the standards used by files similar to it, i.e., to be similar to other .h files if the file is a C/C++ header. The rules for formatting each type of file are given in the following section.

  2. After formatting, in almost all cases the file must be put in the CVS system. The only type of files which should NOT be placed in the CVS are the following:

    To put a file in CVS, follow the steps in the CVS usage section.

  3. Once placed in the CVS, the configure script must be updated, if necessary, to include the name of the new file in the appropriate list. For example, if a new C++ object is being added and there are two new files newobj.C and newobj.h, the names of these files would go into the lists of VMD C++ source code and header files in the configure script.

File formats

There are several types of files which may be added to the whole set of VMD working files. This section describes how to format them, and where to put them.

Many types of files (particularly, C/C++/Fortran source code or header files, Latex documentation files, and shell script files) require an CVS header at the beginning of the file. This header should be placed at the very beginning, before any other text in the file. It consists of a set of comment lines which describe the name, purpose, and history of revisions to the file. This is done by using CVS keywords embedded in the comments, which are replaced by the proper values when the file is checked out, and by having a section in the comments for a basic description of the purpose of the file. Templates of CVS headers for each of the different file types which require them are provided in the directory CVS. When a new file is created, a copy of the relevant header template should be placed at the top of the file, and the file description inserted as comments in the section of the template provided for this purpose. The descriptions below of how to format each file also describe the name of the CVS template to use.

Id:
pg_codestyle.dox,v 1.9 2008/03/04 20:15:49 johns Exp


Generated on Wed Jul 17 02:46:11 2019 for VMD (current) by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002