CS 294-73 (CCN 27241)Software Engineering for

Scientific Computing

http://www.cs.berkeley.edu/~colella/CS294

Lecture 4: Software Engineering Practices

08/25/2011 CS294-73 – Lecture 6

Coding Standards

• When any two have gathered to work on a code, there shall be ill feelings about how the other codes things.

• Ignoring these issues leads to slowly building resentment

- It also leads to functionally inert code changes for style reasons, that look like development in the RCS logs

• So, Coding Standards. - You can get mad at the standard, and want to change the standard, but

it isn’t about your co-workers.

• Goals of a Coding Standard- Good formatting accompanies good structure (reference)- Easier to read code is often easier to understand

• Full Version of Coding Standard Provided from cvs repo>cvs checkout ChomboDoc/CodingStandard

2

08/25/2011 CS294-73 – Lecture 6

Highlights from Coding Standard

• Headers- // Copyright Notice (yes, writing code with us gets open-sourced)

#ifndef _EBAMR_H_

#define _EBAMR_H_

#include “yourincludesGoHere.H”

#include <systemHeadershere.H>

#include "NamespaceHeader.H”

class BillyBob

{

}

#include “NamespaceFooter.H”

#endif

3

08/25/2011 CS294-73 – Lecture 6

Source files: .cpp

#ifdef CH_LANG_CC

/*

* _______ __

* / ___/ / ___ __ _ / / ___

* / /__/ _ \/ _ \/ V \/ _ \/ _ \

* \___/_//_/\___/_/_/_/_.__/\___/

* Please refer to Copyright.txt, in Chombo's root directory.

*/

#endif

#include "BitSet.H"

#include <cstdlib>

#include <cstdio>

#include "MayDay.H"

#include "SPMD.H"

#include ”NamespaceHeader.H"

BitSet BitSetIterator::emptyBitSet = BitSet(); // class statics are at top of source file

BITSETWORD BitSet::trueMasks[BITSETWORDSIZE];

int BitSet::initialize()

{

.

#include ”NamespaceFooter.H"

4

08/25/2011 CS294-73 – Lecture 6

Namespace

• What is this namespace thing ?• Chombo can be conditionally compiled to be contained

in a C++ namespace. - This is put in your code by the NamespaceHeader.H and NamespaceFooter.H files.

• Possible Chombo namespaces- Chombo, D1, D2, D3 etc.

• Allows Chombo to be linked with a library where we might have a collision

- For instance, Chombo and BoxLib both have a class Box

• Allows different dimension builds of Chombo to be linked with each other: Mixed Dim applications

5

08/25/2011 CS294-73 – Lecture 6

Doxygen comments

• Code comments should be recognizable by documentation parsers like doxygen

- That is, you will document your code in doxygen format /// assignment operator. copies pointer member

/** copies pointer member and integer pointer, decreases refcount of rhs member before assignment. this refcount increased my one. */

inline const RefCountedPtr<T>& operator =(const RefCountedPtr<T>& rhs);

/// dereference access operator. use like a pointer derefence access function.

inline T* operator ->();- When the make doxygen target is executed this will generate html

documentation, or LaTeX reference manual material

6

08/25/2011 CS294-73 – Lecture 6

Names• Variable names follow the convention:

- Member variables begin with an m as in m_memVar.- Argument variables begin with an a as in a_argVar. - Static variables begin with an s as in s_statVar.- Global variables begin with an g as in g_globVar.

- Note, the use of global variables is heartily discouraged!

• Function names are likeThis()- This applies to class member functions and stand-alone functions.

• Function arguments are named. - For example, this is o.k.: int cramp(int base, int power);, but

this is not: int cramp(int, int);.

• Argument names are identical in definitions and declarations.

• All modified arguments come before all unmodified arguments. Default values are discouraged.

7

08/25/2011 CS294-73 – Lecture 6

Indentation and Alignment

• This one we fight over, but what the hey.void AMRPoissonOp::applyOpNoBoundary(LevelData<FArrayBox>& a_lhs,

const LevelData<FArrayBox>& a_phi)

{

CH_TIME("AMRPoissonOp::applyOpNoBoundary");

LevelData<FArrayBox>& phi = (LevelData<FArrayBox>&)a_phi;

const DisjointBoxLayout& dbl = a_lhs.disjointBoxLayout();

DataIterator dit = phi.dataIterator();

phi.exchange(phi.interval(), m_exchangeCopier);

for (dit.begin(); dit.ok(); ++dit)

{

const Box& region = dbl[dit];

FORT_OPERATORLAP(CHF_FRA(a_lhs[dit]),

CHF_CONST_FRA(phi[dit]),

CHF_BOX(region),

CHF_CONST_REAL(m_dx),

CHF_CONST_REAL(m_alpha),

CHF_CONST_REAL(m_beta));

}

}

8