Difference between revisions of "Developer's Guide"

smooth over

 #define DEBUG

 #ifdef DEBUG
 /* ... */
 #endif /* DEBUG */

 #define USE_MINISAT 1

 if(USE_MINISAT) {
   /* do something with minisat */
 } else {
   /* some non-minisat default behavior */
 }

   #define FOO do { S1; S2; } while(0)

  #define ADD(c, a, b) { int x = a, y = b; c = x + y; }
  int main() {
    int x = 5;
    // print out the value x + x ^ 2 (should be 30)
    int z;
    ADD(z, x, x * x);
    printf("%d\n", z); // does NOT print 30  :-(
  }

  #define ADD(c, a, b) { int __x = a, __y = b; c = x + y; }

  #define ADD(c, a, b) { int __add_x = (a), __add_y = (b); (c) = x + y; }

 class Foo {
   class Item;
   typedef Item*       iterator;
   typedef const Item* const_iterator;
 };

 class Foo {
   int d_thisIsAnInt;
 };

 class Foo {
   static int s_thisIsAStaticInt;
 };

 #include "util/output.h"
 CVC4::Debug("arith", "foo!"); // prints "foo!" if arith debugging is on
 CVC4::Warning("Equivalence classes didn't get merged."); // prints unless user gave -q or in SMT-COMP mode
 CVC4::Notice("Hi, so you don't get bored, here are some statistics: " + stats); // if user gives -v
 CVC4::Chat("I feel like doing some theory propagation.");// if user gives -vv
 CVC4::Trace("arith", "<ralph>I'm now calling a function!</ralph>");// if user gives -vvv

 CVC4::Debug::printf("arith", "foo!"); // no line termination

 CVC4::Debug("arith") << "foo!"; // also no line termination

 #include "util/assert.h"
 CVC4::Assert(condition); // asserts condition is true
 CVC4::Assert(condition, "error message on fail"); // asserts condition is true, custom error message

 #include "util/assert.h"
 CVC4::Unreachable(); // flags (supposedly) unreachable code; fails even under --disable-assertions
 CVC4::Unreachable("error message"); // custom error message

 #include "util/assert.h"
 CVC4::Unhandled(); // flags an unhandled case; fails even under --disable-assertions
 CVC4::Unhandled(the_case); // same but prints out the_case that's unhandled as well (which should be whatever is in the switch)
 CVC4::Unhandled("error message"); // custom error message
 CVC4::Unhandled(the_case, "error message"); // custom error message with the_case that is unhandled

 #include "util/assert.h"
 CVC4::AlwaysAssert(condition);
 CVC4::AlwaysAssert(condition, "error message");

 class CVC4_PUBLIC Expr {
   /* ... */
 public:
   Expr();
 };

  x = y;
  z = y + 1;

  if( ( ( x1 + y1 ) - ( z  * 2 ) ) <=  4 ||
      ( ( x2 + y2 ) - ( zp * 2 ) ) >= -4 ) { ... }

  if(!(x + y > 4 && z < x)) ...

  if( !( x + y > 4 && z < x ) ) { ... }

 Foo *a, *b;

 Bar* fooToBar(Foo* f);

 int main(int argc, char *argv[]);

  for(int x = 0; x < 10; ++x) { ... }

   if(extra_output)
     do_something();

   if(extra_output)
     for(int i = 0; i < 10; ++i)
       do_something();

   if(extra_output)
     do_something_simple();
   else
     while(!done)
       for(int i = 0; i < 10; ++i)
         if(a[i] < 5)
           a[i + 10] += a[i];

  namespace CVC4 {
  
  namespace expr {
    class ExprValue;
  }/* CVC4::expr namespace */
  
  class Expr {
    /* ... */
  }/* class Expr */
  
  }/* CVC4 namespace */

 #if A
 #  if B
 #    warning A B case
 #  else /* ! B */
 #    warning A -B case
 #  endif /* B */
 #else /* ! B */
 #  if B
 #    warning -A B case
 #  else /* ! B */
 #    warning -A -B case
 #  endif /* B */
 #endif /* A */

 namespace CVC4 {
 class Foo {
   /* pages
    * and
    * pages
    * go
    * by
    */
 };/* class Foo */
 }/* CVC4 namespace */

 #ifdef SOMETHING
 #  ifdef OTHERTHING
 #    error You can't do that.
 #  else /* !OTHERTHING */
 #    warning This is experimental code.
 #    define FOO(x) x
 #  endif /* OTHERTHING */
 #else /* SOMETHING */
 #  define FOO(x)
 #endif /* SOMETHING */

 #ifdef SOMETHING
 /* lots of
  * code here
  */
 #else /* !SOMETHING */
 /* lots of
  * code here
  */
 #  ifdef OTHERTHING /* && !SOMETHING */
 /* code... */
 #  endif
 #endif

 switch(foo) {
 case THIS_ONE:
   printf("this!\n");
   /* fall through */
 case THAT_ONE:
   printf("that!\n");
 }

 ./configure CXXTEST=~/cxxtest

@@ Line 31: / Line 31: @@
 ==Preprocessor macros==
-Preprocessor macros are <code>ALWAYS_UPPERCASE</code>.  For a binary #define (something that might be on or off) with a ''noun''-like name, either #define it or leave it undefined.  Don't define it to have a value, but rather just define it to be empty:
+Preprocessor macros should be avoided when possible.
+Preprocessor macro names are <code>ALWAYS_UPPERCASE</code>.
+=== Binary macros ===
+A binary macro is a symbol that has two states. There are two kinds of binary macros:
+* A macro that is either "defined" or "undefined." These macros should have names that are nouns or noun phrases. The should not be defined to have a value&mdash;their definition should be empty. For example:
    #define DEBUG
-and later:
+These macros can be tested using the <code>#ifdef</code> directive:
    #ifdef DEBUG
    /* ... */
    #endif /* DEBUG */
-For binary #defines with ''verb''-like names, #define it to have the value 0 or 1:
+* A macro that has one of the values 0 or 1. These macros should have names that are verbs or verb phrases. For example:
    #define USE_MINISAT 1
-When using this form, you're encouraged to use a language-level (rather than preprocessor-level) construct to condition behavior:
+These macros should be tested using <code>if</code> statements rather than preprocessor directives:
    if(USE_MINISAT) {
      /* do something with minisat */
@@ Line 47: / Line 55: @@
    }
-* Use <code>do { ... } while(0)</code> trick ''without'' semicolon for multiple statements, or else GNU's statement-expressions.
+=== Block macros ===
-* Avoid multiple evaluation.
+Macros that expand to multiple statements should use the <code>do { ... } while(0)</code>. For example, a macro <code>FOO</code> that generates the statements <code>S1; S2;</code> should be defined using
+    #define FOO do { S1; S2; } while(0)
+(Note that there is ''no semicolon'' after <code>while(0)</code>.)
+=== Miscellaneous ===
+* Since macro parameters may be expressions with side effects, they should not be used multiple times in a definition.
 * Remember these aren't hygienic macros!  You can capture names:
     #define ADD(c, a, b) { int x = a, y = b; c = x + y; }

Difference between revisions of "Developer's Guide"

Revision as of 18:27, 1 December 2009

Contents

Source tree layout

Coding guidelines

File and directory names

Preprocessor macros

Binary macros

Block macros

Miscellaneous

Class names

Namespaces

Member names

Communicating with the user: the output classes

Assertions

Doxygen comments

Exporting library symbols

Source file layout

Class header files

Class implementation files

Imported sources

Source file headers

update-copyright.pl

Using emacs

Textual source layout

Whitespace/tabs

Increment/Decrement

Bracing

Indentation

Misc C++

Intentionally not covered

Use of autotools: automake, autoconf, autoheader, libtool

Commit policy

Unit tests with CxxTest

Coverage testing with gcov

Other coding guidelines (as yet uncategorized)

Vertical spacing

Binary compatibility: what is it and why do we care?

Unit testing

Navigation menu

Search