---

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:

• Use the same style consistently throughout the source code.
• If editing or adding to existing source files, follow the existing formatting style that's already in place, even if you hate it. That's far better than having a mishmash of several styles within one source file.
• Comment your code with Doxygen comment blocks wherever possible so that the comments make it into autogenerated documentation. This is especially important for header files since they are what other developers will read and or reference most frequently.

Naming conventions

Most of the naming practices employed within the VMD source tree are based on a few common sense principles:

• Local variables, parameters for short/simple functions, and short-lived temporary variables have no need for long verbose descriptive names. By their very nature, they are used in a very small scope and so their function is typically obvious within a single page of source code. Variable names like a, b, c, i, x, y, tmp, cmdptr, and index, are all excellent examples of names for local variables used in a very small scope.
• Class member variables while not global, can conceivably have name collisions with function parameters or local variables, and so they should be named somewhat more descriptively than local variables and function parameters.
• Functions with global scope should have longer, descriptive names that are unlikely to collide with system routines or third party libraries.
• Dangerous, globally accessible, or otherwise delicate variables and functions should have very long descriptive names and should be well commented wherever they are referenced or called.

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:
   • Binary executable files, i.e., binary executable files which are in the bin directory.
   • Image files used for the documentation, i.e., which are in the doc/pictures directory. There is a single local copy of these files, to prevent remote CVS checkouts from bogging down.
   • Libraries, including the library archive file and the library header files. These should all be in a single place, and all users should simply have a link from their working lib directory to the single official VMD lib directory.
   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.

• Documentation text files The user documentation for VMD is in Latex, and files should have a .tex extension. The files should all be placed in the doc directory, be put in the CVS, and have the standard CVS header RCS/RCSheader.tex prepended.

• Documentation image files Image files for the documentation should be placed in the directory doc/pictures, which should be a link to a directory writable by all people working on VMD. These files are not presently placed in CVS due to their size.

• Source code files All source code files, either C, C++, or Fortran, should be placed in the src directory, along with all header files. These files should be entered into the CVS; a copy of the CVS template RCS/RCSheader.h should go at the start of header files, and a copy of RCS/RCSheader.c should be placed at the start of C and C++ source files. Fortran files should begin with a copy of the file RCS/RCSheader.f.

  All header files should bracket their text between a #ifndef ... #endif pair, and define a macro to indicate the header file has been processed. For example, right after the CVS header should come the text

  #ifndef DISPLAYDEVICE_H
  #define DISPLAYDEVICE_H
  #endif
  

• Shell script files Files which are Bourne shell or C shell scripts should be placed, most likely, in either the main working directory or the bin directory. These should be entered into the CVS, and have the CVS header RCS/RCSheader.make placed at the beginning. When adding such files to the CVS, care must be taken to have the comment leader for the CVS file set properly. This is done by using the command-line switch

        -c"# "
      

  added to the options to the rcs program (described in the CVS usage section.

• Data files Files which contain data or configuration parameters needed by VMD should be placed in the data directory, and be put in the CVS. In most cases, the # symbol is the comment character, and so they can have the same type of CVS header as used for shell scripts. This is true, for example, for the file data/.vmdrc, which is in the CVS.

Id:

pg_codestyle.dox,v 1.10 2020/02/24 18:05:20 johns Exp

---