Styleguide

csauls · Joined: 27 Mar 2004 Posts: 278

Until further notice, the styleguide to be used is hosted at:
http://www.kydance.net/~invironz/proj.php?sect=sinbad&sub=styleguide

------------------------------

Post questions, suggestions, etc in this topic.

First questions:

Access Attributes: should we use attribute blocks public{...}/private{...}/protected{...} or should individual entities be attributed, such as 'public int somefield;' ...? And if using blocks, should they be indented in classes or not? Or in other words, would this be acceptable:

larsivi · Posted: Mon Apr 26, 2004 3:27 pm Post subject: Re: Styleguide

csauls · Joined: 27 Mar 2004 Posts: 278

larsivi · Posted: Tue Apr 27, 2004 2:15 am Post subject:

Coin (which I've mentioned before) use this format for their documentation (and they use Doxygen to generate the HTML, etc).

/*!
Some stuff.
More stuff
Commands to Doxygen is /prepended /with /slashes such
as /e which means emphasize (bold or italic, don't remember)
*/

I think the '!' is the token necessary by Doxygen, although it understands several format AFAIK.

On www.doxygen.org, it is said that Doxygen have preliminary support for D.

larsivi · Posted: Wed Apr 28, 2004 1:33 am Post subject: FIXMEs

Another thing;
Wherever in the code we feel that we haven't found the optimal solution, or something needs to be implemented, or we know that it is buggy or anything else, we should enter something like this:

// FIXME: This code is _bad_ See url this and that. larsivi 200404228

Thus we know there might be a problem, where to find more info on it, who found it or reported it and when.

csauls · Joined: 27 Mar 2004 Posts: 278

On the same note, I'd like to see a bottom-of-source changelog. Something along the lines of:

larsivi · Posted: Wed Apr 28, 2004 2:41 pm Post subject:

Changelogs are great, but isn't good commit messages enough? Then you can request all logs for a file.

On comment format:

Doxygen understands the following two.

csauls · Joined: 27 Mar 2004 Posts: 278

I think I prefer the /*! format as well, its just more obvious that its something other than a basic comment, while the doubled * is something I'd read right past.

As to changelogs.. I forget one can even attach messages to commits.. I'm just not used to working with Svn. We can give that a shot first, and add the bottom-of-source logs if we decide we need them.
_________________
Chris Nicholson-Sauls

csauls · Joined: 27 Mar 2004 Posts: 278

First: the styleguide has been updated. Changes include some cleanup, addition of Classes and Singletons sections, and a list of sections at the top for quick browsing.

Second: should I isolate the styleguide into a simple html file and stick it in the repository? And perhaps go ahead and shove a copy of the LGPL in there too.
_________________
Chris Nicholson-Sauls

csauls · Joined: 27 Mar 2004 Posts: 278

With the addition of mixins, and after a little re-thinking, the Class sytleguide needs updating. Basically, the following hypothetical class Foo demonstrates the new proposed style.

kris · Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific

larsivi · Posted: Mon May 31, 2004 3:55 am Post subject: identifiers

I think that aligned identifiers are, well, not very practical. If you find out that you need to declare a variable with a hellishly long type name, e.g. ExampleFrameListenerManager, you suddenly have to realign all other variables. I think it's better to just group declarations of the same type:

csauls · Joined: 27 Mar 2004 Posts: 278

There's some truth in that, and I have had a few times where I'd had long class/struct names that made the spacing wide, but truly I don't think I've yet dealt with any names as long as some of OGRE's in D code before, so I hadn't even considered that effect. I may just leave that bit up to programmer's preferance then.

Oh and on a slightly more important note, the styleguide will get added to the repository soon, since the Invironz site is indefinitely down due to... well, problems.
_________________
Chris Nicholson-Sauls