SNAP C++ Programming Guide

A brief description consists of ///, followed by one line of text:

/// Returns ID of the current node.

A detailed description consists of a brief description, followed by ##<tag_name>:

/// Returns ID of NodeN-th neighboring node. ##TNodeI::GetNbrNId

Text for <tag_name> from file <source_file> is placed in file doc/<source_file>.txt. Tag format is:

/// <tag_name>
...<detailed description>
///

For example, a detailed description for ##TNodeI::GetNbrNId from file snap-core/graph.h is in file snap-core/doc/graph.h.txt (see these files for more examples):

/// TNodeI::GetNbrNId
Range of NodeN: 0 <= NodeN < GetNbrDeg(). Since the graph is undirected
GetInNId(), GetOutNId() and GetNbrNId() all give the same output.
///

Additional Documentation Commands

Snap documentation also uses the following Doxygen commands:

• ///<: for comments associated with variables.
• @param: for comments associated with function parameters.
• \c: specifies a typewritter font for the next word.
• <tt>: specifies a typewritter font for the enclosed text.

More details on how to use these commands are provided in specific sections below.

Function Declarations

Every function declaration should have a description immediately preceding it about what the function does and how to use it. In general, the description does not provide how the function performs its task. That should be left to comments in the function definition.

Function Definitions

Each function definition should have a comment describing what the function does if there's anything tricky about how it does its job. For example, in the definition comment you might describe any coding tricks you use, give an overview of the steps you go through, or explain why you chose to implement the function in the way you did rather than using a viable alternative. If you implemented an algorithm from literature, this is a good place to provide a reference.

Note you should not just repeat the comments given with the function declaration, in the .h file or wherever. It's okay to recapitulate briefly what the function does, but the focus of the comments should be on how it does it.

Function Parameters

It is important that you comment the meaning of input parameters. Use @param construct in the comments to do that. For the example of function void DelNode(const int& NId); above, its parameter is documented in file doc/*.h.txt as follows:

/// TUNGraph::DelNode
@param NId Node Id to be deleted.
///

Class Data Members

Each class data member (also called an instance variable or member variable) should have a comment describing what it is used for.

TODOs should include the string TODO in all caps, followed by the name, e-mail address, or other identifier of the person who can best provide context about the problem referenced by the TODO. The main purpose is to have a consistent TODO format that can be searched to find the person who can provide more details upon request.

Smart pointers are objects that act like pointers, but automate management of the underlying memory. They are extremely useful for preventing memory leaks, and are essential for writing exception-safe code.

By convention, class names in SNAP start with letter "T" and their corresponding smart pointer types have "T" replaced with "P".

In the following example, variable Graph is defined as an undirected graph. TUNGraph is the base type and PUNGraph is its corresponding smart pointer type:

PUNGraph Graph = TUNGraph::New();

The following example shows how an undirected graph is loaded from a file:

{ TFIn FIn("input.graph"); PUNGraph Graph2 = TUNGraph::Load(FIn); }

To implement smart pointers for a new class, only a few lines need to be added to the class definition.

The original class definition:

class TUNGraph {
  ...
};

The original class definition after smart pointers are added:

class TUNGraph;

typedef TPt<TUNGraph> PUNGraph;

class TUNGraph {
   ...
private:
  TCRef CRef;
  ...
public:
  ...
  static PUNGraph New();                 // New()  method
  static PUNGraph Load(TSIn& SIn);       // Load() method
  ...
  friend class TPt<TUNGraph>;
};

The new code declares PUNGraph, a smart pointer type for the original class TUNGraph. A few new definitons have been added to TUNGraph: CRef, a reference counter for garbage collection; New(), a method to create an instance; and a friend declaration for TPt<TUNGraph>. The Load() method for a smart pointer class returns a pointer to a new object instance rather than no result, which is the case for regular classes.

An example of definitions for the New() and Load() methods for TUNGraph are shown here:

static PUNGraph New() { return new TUNGraph(); }
static PUNGraph Load(TSIn& SIn) { return PUNGraph(new TUNGraph(SIn)); }

SNAP defined streams are:

• TSIn is an input stream.
• TSOut is an output stream.
• TSInOut is an input/output stream.
• TStdIn is the standard input stream.
• TStdOut is the standard output stream.
• TFIn is a file input stream.
• TFOut is a file output stream.
• TFInOut is a file input/output stream.
• TZipIn is a compressed file input.
• TZipOut is a compressed file output.

Assertion names in SNAP use the following convention for the first letter:

• Assert: compiled only in the debug mode, aborts when the assertion is false.
• IAssert: always compiled, aborts if the assertion is false.
• EAssert: always compiled, does not abort, but throws an exception.

Some common SNAP assertions are:

• Assert verifies the condition. This is the basic assertion.
• AssertR verifies the condition, provides a reason when the condition fails.

SNAP also implements assertions that always fail. These are used when the program identifies a critical error, such as being out of memory. Fail assertions are:

• EFailR throws an exception with a reason.
• FailR prints the reason and terminates the program.
• Fail terminates the program.

Examples of assertion usage:

AssertR(IsNode(NId), TStr::Fmt("NodeId %d does not exist", NId));
EFailR(TStr::Fmt("JSON Error: Unknown escape sequence: '%s'", Beg).CStr());

Use int for integers that are not going to be too large, e.g., loop counters. You can assume that an int is at least 32 bits, but don't assume that it has more than 32 bits.

Functions should not return values of type TSize (size_t). Instead, use fixed size arguments for function return values, like int32, int64.

Do not use the unsigned integer types, unless the quantity you are representing is really a bit pattern rather than a number, or unless you need defined twos-complement overflow. In particular, do not use unsigned types to say a number will never be negative. Instead, use assertions for this purpose.

To print 64-bit integers, use TUInt64::GetStr() for conversion to string and the %s print formatting conversion:

int64 Val = 123456789012345;
TStr Note = TStr::Fmt("64-bit integer value is %s", TUInt64::GetStr(Val).CStr());

SNAP exceptions are implemented with TExcept::Throw and PExcept.

TExcept::Throw throws an exception:

TExcept::Throw("Empty blog url");

PExcept catches an exception:

try {
  ...
} catch (PExcept Except) {
  SaveToErrLog(Except->GetStr().CStr());
}

Declared variables and parameters can be preceded by the keyword const to indicate the variables are not changed (e.g., const int Foo). Class functions can have the const qualifier to indicate the function does not change the state of the class member variables (e.g., class Foo { int Bar(char Ch) const; };).

const variables, data members, methods and arguments add a level of compile-time type checking. It is better to detect errors as soon as possible. const can also significantly reduce execution time. Therefore we strongly recommend that you use const whenever it makes sense to do so:

• If a function does not modify an argument passed by reference or by pointer, that argument should be const.
• Declare methods to be const whenever possible. Accessors should almost always be const. Other methods should be const if they do not modify any data members, do not call any non-const methods, and do not return a non-const pointer or non-const reference to a data member.
• Consider making data members const whenever they do not need to be modified after construction.

Put const at the beginning of a definition as in const int* Foo, not in the middle as in int const *Foo.

Note that const is viral: if you pass a const variable to a function, that function must have const in its prototype (or the variable will need a const_cast).

Macros are not nearly as necessary in C++ as they are in C. Instead of using a macro to inline performance-critical code, use an inline function. Instead of using a macro to store a constant, use a const variable. Instead of using a macro to "abbreviate" a long variable name, use a reference. Instead of using a macro to conditionally compile code ... well, don't do that at all (except, of course, for the #define guards to prevent double inclusion of header files). It makes testing much more difficult.

Use sizeof(varname) because it will update appropriately if the type of the variable changes. sizeof(type) may make sense in some cases, but should generally be avoided because it can fall out of sync if the variable's type changes.

Struct Data;
memset(&Data, 0, sizeof(Data));

memset(&Data, 0, sizeof(Struct));

Use namespace TSnapDetail to encapsulate local functions.

Do not define any new namespaces, use TSnap for global functions and TSnapDetail for local functions.

Do not use a using-directive to make all names from a namespace available:

// Forbidden -- This pollutes the namespace.
using namespace Foo;

Use namespace TSnap for global functions and namespace TSnapDetail for local functions. See file alg.h for an example.

If you must define a nonmember function and it is only needed locally in its .cpp file, use static linkage: static int Foo() {...}, or namespace TSnapDetail to limit its scope:

namespace TSnapDetail {                // This is in a .cpp file.

// The content of a namespace is not indented
enum { kUnused, kEOF, kError };        // Commonly used tokens.
bool AtEof() { return pos_ == kEOF; }  // Uses our namespace's EOF.

}  // namespace

double GetDegreeCentr(const PUNGraph& Graph, const int& NId);

When defining a function, parameter order is: inputs, then outputs.

Input parameters are usually values or const references, while output and input/output parameters are non-const references. In the following example, Graph is an input parameter, and InDegV and OutDegV are output parameters:

void GetDegSeqV(const PGraph& Graph, TIntV& InDegV, TIntV& OutDegV);

When ordering function parameters, put all input-only parameters before any output parameters. In particular, do not add new parameters to the end of the function just because they are new; place new input-only parameters before the output parameters.

This is not a hard-and-fast rule. Parameters that are both input and output (often classes/structs) muddy the waters, and, as always, consistency with related functions may require you to bend the rule.

We recognize that long functions are sometimes appropriate, so no hard limit is placed on functions length. If a function exceeds about 40 lines, think about whether it can be broken up without harming the structure of the program.

Even if your long function works perfectly now, someone modifying it in a few months may add new behavior. This could result in bugs that are hard to find. Keeping your functions short and simple makes it easier for other people to read and modify your code.

• Typedefs and Enums
• Constants (static const data members)
• Private/Public Classes
• Data Members (except static const data members)
• Private Methods
• Constructors
• Destructor
• Public Methods, including static methods
• Friends

Group the methods so that methods relating to common functionality are grouped together. Method definitions in the corresponding .cpp file should be the same as the declaration order, as much as possible.

If your object requires non-trivial initialization, consider having an explicit Init() method. In particular, constructors should not call virtual functions, attempt to raise errors, access potentially uninitialized global variables, etc.

The struct and class keywords behave almost identically in C++. We add our own semantic meanings to each keyword, so you should use the appropriate keyword for the data-type you're defining.

If in doubt, make it a class.

All of a project's header files should be listed as descendants of the project's source directory without use of UNIX directory shortcuts . (the current directory) or .. (the parent directory). For example, snap-awesome-algorithm/src/base/logging.h should be included as:

#include "base/logging.h"

Within each section it is nice to order the includes alphabetically.

If you need to change such code, the best option is to rewrite it, so that it conforms to the guide. If that is not possible, because rewriting would require more time and effort than you have available, then stay consistent with the local conventions in that code.

SNAP does not contain any Windows specific code. All such code is encapsulated within the GLIB library, which SNAP uses. If you must implement some Windows specific functionality, contact SNAP maintainers.