FoundationDB

Source Code Style Guide


(Van L) #1

Is there a style guide for source code and comments?

For example, how could the following comment be made better? or what is the thinking here?

// The reason for getting a pointer to DatabaseContext instead of a reference counted object is because reference counting will increment reference count for
// DatabaseContext which holds the future of this actor. This creates a cyclic reference and hence this actor and Database object will not be destroyed at all.


(Alex Miller) #2

There is a .clang-format file that was very recently added to the repository, which is the closest we have to a coding style now. Formerly, there wasn’t a defined coding style, and the feel of the code was largely influenced by its author’s opinions.

The comment is describing that DatabaseContext holds the result of calling clientStatusUpdateActor, so having clientStatusUpdateActor hold a reference to the DatabaseContext would cause a cycle of reference counts. Naive reference counting can’t handle cycles, so using reference would cause a memory leak. I’m open to better ways for it to be phrased, but nothing leaps out at me.


(Van L) #3

Here, a line length exceeding 104 columns causes line wrap.

Should the style guide recommend 80 column width for comments?

There should be a process to collect suggestions, polish them through
discussion on chat platforms, forums, emailing lists and then throw
them out or keep them in a style guide.

I’ve created a ##FoundationDB channel on freenode for chat and can
hand ownership to somebody official here. It has been linked to the
##apple channel.

In the code block that follows, lines 430 and 441 are comment
duplicates the style guide could reject for reasons collected and then
point to a wiki for better ways than doing that.

Ideally, comments would read as smoothly as follows in 80 columns or less :-

// It is almost always clear from context what people mean.
// When dealing with computer programs, however, it is important
// to keep the distinction in mind, since the computer is not as
// smart as a person.

Would a tech journo be able to phrase what is going on there without cartwheeling the terms in the one sentence, one sentence?

The C++ section of the style guide has pointers to :-