[boost] Re: Guidelines for library submissions

From: Ed Brey (brey_at_[hidden])
Date: 2000-03-14 14:44:57

[Working with source code using proportional fonts.]

From: "Beman Dawes" <beman_at_[hidden]>
>
> What guidelines do you use? How do you deal with the issues you
raise below?

- Tabs are only used at the beginning of a line and only for
indentation.
- A single space may be used following a sequence of tabs as a
"mini-tab".
- Only the first non-whitespace character of a line is expected to
ever be aligned.
- Comments following code on a line are separated from the code by a
single space.
- There is no arbitrary line-length limit.  Statements are broken onto
multiple lines based on their complexity, so as to optimize the
tradeoff between horiztonal and vertical scrolling.

> What font?
I use a PC with VC and use the 10 point Arial.  Font doesn't matter
though and can be chosen as a matter of taste.

> What printing program?
SuperIDE is the best I've found (http://protostar.hypermart.net/).
It's freeware, and lets you print using proportional fonts with BW
syntax highlighting.  I only use it for printing, not actually as an
IDE.

> What indenting style works best?
As long as you use tabs it doesn't make much difference.  That is to
say all the traditional tradeoffs between styles remain.  For example:

if (foo()) {
    bar();
}

has its pros and cons versus

if (foo())
    {
    bar();
    }

regardless of whether proportional or nonproportional fonts are used.
Personally, I use the first one, except that I pull the opening brace
onto its own line if the body of the block is large or for some reason
feels like it should be set off from the pre-block tokens.  (Note that
I think my email program will convert the tabs to spaces in the above
examples, so just pretend that the indenting was done with a single
tab.)

As far as indent formatting of a class goes, I use this style (here I
explicity spell out the whitespace at the beginning of the line):

class small_class {
[space]public: // The space here acts as a mini-tab.
[tab]void rail(int& i) {
[tab][tab]if (i > max)
[tab][tab][tab]i =max;
[tab]}

[space]private:
[tab]int const max = 3; // Always put type name before "const".
};

which ends up looking something like this:

class small_class {
 public: // The space here acts as a mini-tab.
    void rail(int& i) {
        if (i > max)
            i =max;
    }

 private:
    int const max = 3; // Always put type name before "const".
};

For declarations, I like to put qualifiers like "const" after the
type, since during quick looks, usually it is the type you want to
gleen.  Plus this puts the type at one end of declaration and the name
at the other, which I think makes it easier to pick out the bit you're
looking for.  (I'm talking subconscious picking here, in the course of
reading the code.)  (The positioning of the const qualifier is
something I recently saw done somewhere and have been using for the
last month or two, and so it's still experimental to me.)

> How do other programmers react to your code?
Some think the ideas are pretty neat and the printed code is quite
readable, although none have taken the leap to try experimenting with
using proportional fonts for their on-screen development yet.  On the
other hand, there are a couple that think I'm nuts.

> What happens when you port the code between operating systems?  Does
code that looks good under Windows still look good under Unix or on a
Mac?
I haven't tried it, although I'm sure there would be no problems.
Just set the tab size and font to personal taste.  Actually, I got the
idea for using proportional fonts way back when using Lightspeed
Pascal (IIRC) on my high school's Macintoshes.  As much as I hated
about those machines (no hard drive in 1990, for one), the cleanliness
of the code that the proportional fonts brought was quite appealing.

>  Do you have some sample code you could let us see?
Unfortunately, all the substantial stuff is owned by my company.  But
for a quick example look at a function I wrote for a class assignment:
http://www.cc.edu/~eschmied/code/5.8.4.hpp

Don't look at the file with your browser; instead use a syntax
highlighting editor with a proportional font. (You'll probably prefer
a non-serifed one, such as Arial.  (FWIW, I think a big browser botch
for both IE and Netscape is using serifed fonts by default; screen
resolutions are still too low to support them well.))  Look at
make_loser.  You'll probably find that you can easily make the "for"
line, which is 146 characters long, fit without scrolling.  The nice
part is that this function fits compactly into an area where you can
easily comprehend its structure.  And if this tiny example were part
of a larger algorithm, this part wouldn't be of such a large size that
you lose sight of the whole.

In general, when going through the structure of the code looking for
something, it's nice to have as much structure on the screen at once,
so you can open a couple of windows, truncating the detail in long
comments or code.  Then, which it comes time to dig into detail on a
section, blow up that window and you can see all the details.

For an example of a class definition and implementation, see:
http://www.cc.edu/~eschmied/code/pairing_heap.hpp

A warning that this class is still in progress, so don't look at it
for anything except a formatting example.  I have to make a pairing
heap for school and use it implement the single source, shortest path
algorithm.  My long-term goal, though is to have the pairing heap be a
priority queue with an interface just like std::priority_queue, except
with erase, merge, and increase methods.  Really, though, this is just
a testbed for playing around with a capability model.  I want to have
a single class boost::priority_queue, in which the user passes in as a
template parameter, maybe via a bitset, the desired capabilities
(erase, merge, etc.) and the best implementation is automatically
chosen (complete binary tree, leftist tree, pairing heap).  I think
such a capability model can be used in many places, such as to help
choose between std::list and SGI's slist, and also whether list.size()
should have linear or constant complexity.  Another application may be
to choose between our numerous smart pointers.  If done right, the
default template parameters should work fine in most of the cases just
like existing std classes do, and the capabilities parameter would
only be needed to tweak out better performance or to access rare,
expensive features.

Sorry that I've strayed off topic, but I never seem to get enough time
to work on my ideas, and I kind of wanted to spit out what I was
thinking in case it spurs creativity in the minds of anyone else.