diff --git a/Doc/engineering.html b/Doc/engineering.html index 9d01ebb60..e9d60b347 100644 --- a/Doc/engineering.html +++ b/Doc/engineering.html @@ -20,7 +20,24 @@ beazley@cs.uchicago.edu

(Note : This is a work in progress.) +

Table of Contents

+ + +

1. Introduction

+ The purpose of this document is to describe various coding conventions and organizational aspects for SWIG developers. The idea for this @@ -58,7 +75,9 @@ should be developed within the SWIG project. These rules are primarily drawn from my own experience developing software and observing the practices of other successful projects. +

2. Programming Languages and Libraries

+ All SWIG modules must be written in either ANSI C or one of the scripting languages for which SWIG can generate an interface (e.g., @@ -81,7 +100,9 @@ should always be included inside a conditional compilation block so that it can be omitted on problematic platforms. If you are unsure about a library call, check the man page or contact Dave. +

3. The Source Directory and Module Names

+ All SWIG modules are contained within the "Source" directory. Within this directory, each module is placed into its own subdirectory. The @@ -100,7 +121,9 @@ sure the first letter is capitalized. Also, module names should not start with numbers, include underscores or any other special non-alphanumeric characters. -

4. Include files

+ +

4. Include Files

+ All modules should include a header file that defines the public interface. The name of this header file should be of the form "swigmodule.h" where @@ -150,7 +173,9 @@ extern "C" {

To minimize compilation time, please include as few other header files as possible. +

5. File Structure

+ Each file in a module should be given a filename that is all lowercase letters such as "parser.c", not "Parser.c" or "PARSER.c". Please note that filenames @@ -210,7 +235,9 @@ multiple files. Similarly, you should avoid the temptation to create many small files as this increases compilation time and makes the directory structure too complicated. +

6. Bottom-Up Design

+ Within each source file, the preferred organization is to use what is known as "bottom-up" design. Under this scheme, lower-level functions @@ -248,7 +275,9 @@ benefits particular to C. In particular, a bottom-up design generally eliminates the need to include forward references--resulting in cleaner code and fewer compilation errors. +

7. Functions

+ All functions should have a function header that gives the function name and a short description like this: @@ -279,7 +308,9 @@ Function declarations should NOT use the pre-ANSI function declaration syntax. The ANSI standard has been around long enough for this to be a non-issue. +

8. Naming Conventions

+ The following conventions are used to name various objects throughout SWIG. @@ -362,7 +393,9 @@ typedef struct SwigScanner { Static declarations are free to use any naming convention that is appropriate. However, most existing parts of SWIG use lower-case names and follow the same convention as described for functions. +

9. Visibility

+ Modules should keep the following rules in mind when exposing their internals: @@ -403,12 +436,50 @@ making your changes. -

10. Miscellaneous

+ +

10. Miscellaneous Coding Guidelines

+ + +

11. CVS Tagging Conventions

+ + +Use cvs tag to declare some set of file revisions as related in some +symbolic way. This eases reference, retrieval and manipulation of these files +later. At the moment (2001/01/16 14:02:53), the conventions are very simple; +let's hope they stay that way! + +

+There are two types of tags, internal (aka personal) and external. +Internal tags are used by SWIG developers primarily, whereas external +tags are used when communicating with people w/ anonymous cvs access. +

+ +That's all there is to it. Some example tags: + + + +
+Copyright (C) 1999-2001 +SWIG Development Team