General Suggestions for Coding in OAGear

General Suggestions for Coding in OAGear

Developer Notes

• You need to have relatively new versions of autoconf and automake installed and available in your path. We have tested with and recommend using autoconf-2.59 and automake-1.9.6.

• If you are working from a CVS checkout, keep the following in mind:
  • As general policy, files which are generated from other files should not be checked into CVS.
  • Because file generated by autoconf/automake are not checked in, these need to be created with every new CVS checkout. To do this, run the script: Build/setup-developer in the top level source directory.
  • Before checking in, make sure copyright information is added to all source files. This can be automatically done for all files of specific types (*.cpp, *.h, Makefile.am, *.dox (Doxygen input)) found in the source tree. Go to the top level source directory and run the script: Build/fix-copyright You should probably check to make sure the modifications made by this script are okay. Backup copies are created for all modified files; these are named by appending a tilde (~) to the end of the original filename.

• If you are adding/editing a source file, try to remember to add an "Author" comment somewhere near the top, and use "Changelog" comments for major updates.

• Please be aware of where your code comes from. Do not use code you are not licensed or authorized to use. Be aware of copyrights.

Coding Style Guidelines

OA Gear should generally follow the OpenAccess coding style guidelines (see doc/oa/html/styleguide/index.html in the OA documentation). The following changes/clarifications should be noted:

• All OA Gear objects must reside in an appropriate C++ namespace:
  • Bazaar Objects: oagBazaar
  • Decision Diagram Objects: oagDd
  • Functional Representation Objects: oagFunc
  • Placement Objects: oagPlace
  • Timer Objects: oagTimer
  • Tools Objects: oagTools
  • Utility Objects: oagUtil Change: Was unspecified in original OA guidelines. Rationale: This minimizes namespace collisions between packages.

• Each class in the oaGear namespace must reside in its own file, named using the naming convention from the original OA guidelines. Change: Was unspecified in original OA guidelines. Rationale: This allows code readers to find the right files easily.

• Inner classes and structs (i.e. nested classes within classes) are allowed. Change: Was prohibited in original OA guidelines. Rationale: If small helper classes were declared in the oaGear namespace, they would have to be given their own files (see previous guideline), cluttering up the namespace and directory. This will allow such helper classes to reside in the file of their containing class.

• Tabs should not appear in code. Change: Was ambiguous in original OA guidelines. Rationale: Some editors use tabs for indentation. As tabs can be represented by variable numbers of spaces, they should be avoided so that files may have a uniform appearance in any editor.

• Code must compile with no warnings using the g++ flags: -W -Wall -Wno-non-virtual-dtor -Wno-ctor-dtor-privacy Change: Was unspecified in original OA guidelines. Rationale: Compiler warnings are often signs of buggy or poorly written code. The exceptions to -Wall avoid problems in OA itself.

• External APIs must be documented using Doxygen. Doxygen markup for a class must appear in the .h file and not the .cpp file for that class. Change: Was unspecified in original OA guidelines. Rationale: Standardizing the location of Doxygen markup makes it easier to find it.

• Use C++ static_cast<> instead of traditional C casts. Change: Was unspecified in original OA guidelines. Rationale: This makes casting easier to find when reading code.

• Protect header files from multiple inclusion with the following: If the filename is oagFooBar.h, use #if !defined(oagFooBar_P) #define oagFooBar_P ... #endif Change: Was ambiguous in original OA guidelines. Rationale: Header file protection should be standardized in order to avoid mistaken exclusion of unrelated headers.

• Lex files must be named with a .lxx suffix. Yacc files must be named with a .ypp suffix. Change: Was unspecified in original OA guidelines. Rationale: Standard naming allows common Makefile stubs to be written.

Tips for programming

Tools to format code --------------------

There are a number of tools that can help format code to comply with the coding standards.

indent ------

The utility "indent" should be available on most Linux systems. This indents C code well, and C++ code to a limited extent.

"indent" has many options to control its behavior. The file "Build/indent-sources" (from CVS) is a shell script wrapper which sets the options which most closely meet the OA style guidelines. Alternatively, you can instead create a file /home/zerocool/.indent.pro with the contents:

-nbad -bap -nbbb -sob -br -ce -cdw -cli2 -ss -npcs -cs -saf -saw -saf -sai -saw -di1 -nbc -bfda -psl -brs -i4 -ci4 -lp -ts8 -ip20 -nut -l80 -hnl

Note that you can run "indent" on a file, or use it as a filter (useful with the vim filter command '!').

There are several common places where "indent" fails to do the right thing, and some manual fixup will be required. The <> symbols for templates and variable declarations with initializers, e.g. MyClass x(42); are usually confused for other constructs.

vi/vim ------

Configured using the file /home/zerocool/.vimrc . Example .vimrc file:

set shiftwidth=4 autoindent ruler nocompatible autocmd BufEnter *.c,*.cc,*.cpp,*.h set cindent expandtab softtabstop=4 syntax on

shiftwidth=4 : Sets indentation levels to be 4 spaces, as required by the style standard. expandtab : Tab characters are converted to spaces. softtabstop=4 : Changes the behavior of the TAB key to move 4 spaces instead of the normal 8. The "tabstop" option should be left to 8, in order to expand existing tabs to 8 spaces. cindent : Turns on automatic C-style code indentation.

Note that some options are only turned on for *.{cpp,h} files. This is to prevent tabs from being expanded in Makefiles, a serious error.

The keystrokes >{motion} and <{motion} perform indentation (move the text [shiftwidth] spaces to the right) and unindentation (move the text [shiftwidth] spaces to the left) on the text defined by {motion} (the standard vi motion sequences, e.g. >> indents a line, >} indents a paragraph unit, etc.).

The keystroke ={motion} performs C-style re-indentation on the text defined by {motion} (e.g. =} re-indents a paragraph unit). shiftwidth should be defined to be the desired indentation level.

Modelines are comments that can be added to files so that appropriate vi settings are enabled when editing that file. As an OA Gear standard, .{cpp,h} files are permitted to have the following modeline as the last line in the file:

vim: ci et sw=4 sts=4

emacs -----

Example configuration using /home/zerocool/.emacs :

(set-foreground-color "white") (set-background-color "black") (global-font-lock-mode t)

(require 'cc-mode) (defun my-build-tab-stop-list (width) (let ((num-tab-stops (/ 80 width)) (counter 1) (ls nil)) (while (<= counter num-tab-stops) (setq ls (cons (* width counter) ls)) (setq counter (1+ counter))) (set (make-local-variable 'tab-stop-list) (nreverse ls)))) (defun my-c-mode-common-hook () (setq tab-width 5) ;; modify this (my-build-tab-stop-list tab-width) (setq c-basic-offset 4) ;; modify this (setq indent-tabs-mode nil)) ;; force only spaces for indentation (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)

---