FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

Styleguide

 
Post new topic   Reply to topic     Forum Index -> Sinbad
View previous topic :: View next topic  
Author Message
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Mon Apr 26, 2004 12:43 pm    Post subject: Styleguide Reply with quote

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:
Code:

class Foo {
public {
  // public junk
}
protected {
  // personal junk
}
private {
  // hidden junk
}
}


Comments: what kind of format is best for "header" comments over classes/functions/methods? I'm personally fond of:
Code:

/***********************************************************************
  Stuff goes here
***********************************************************************/

_________________
Chris Nicholson-Sauls
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Mon Apr 26, 2004 3:27 pm    Post subject: Re: Styleguide Reply with quote

csauls wrote:
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:


Actually, I'm most fond of unindented colonized attributes;

public:

protected:

private:

There is more than enough braces to go around already.

csauls wrote:

Comments: what kind of format is best for "header" comments over classes/functions/methods? I'm personally fond of:
Code:

/***********************************************************************
  Stuff goes here
***********************************************************************/


I think that one is over the top. I've always used (sorta coming from Java)

Code:

/*
 * Some stuff
 * More stuff
 */
Back to top
View user's profile Send private message
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Mon Apr 26, 2004 3:33 pm    Post subject: Re: Styleguide Reply with quote

larsivi wrote:
There is more than enough braces to go around already.


True enough.

larsivi wrote:
I think that one is over the top. I've always used (sorta coming from Java)
Code:

/*
 * Some stuff
 * More stuff
 */


I never used that style, even in Java, but its not bad. Probably easier to make meaninful to documentors... which reminds me I need to look at doxygen. I'll flip a coin later if no one else "votes". Smile
_________________
Chris Nicholson-Sauls
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Tue Apr 27, 2004 2:15 am    Post subject: Reply with quote

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.
Back to top
View user's profile Send private message
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Wed Apr 28, 2004 1:33 am    Post subject: FIXMEs Reply with quote

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.
Back to top
View user's profile Send private message
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Wed Apr 28, 2004 11:13 am    Post subject: Reply with quote

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

Code:

/*  CHANGES
 *
 *  2004 04 30 larsivi
 *    Implemented foo.bar
 *    Added hook... blah blah
 *
 *  2004 04 28 csauls
 *    Fixed logic in class.method
 *    Resolved recursive... blah blah
 *
 */


I'd like to officially lay the blame on you, btw, for my adopting that commenting style. Its addictive.
_________________
Chris Nicholson-Sauls
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Wed Apr 28, 2004 2:41 pm    Post subject: Reply with quote

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.

Code:

/**
 * This is originally javadoc.
 */


Code:

/*!
 * This originated from the Qt documentation.
 */


I vote for the last.
Back to top
View user's profile Send private message
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Wed Apr 28, 2004 3:02 pm    Post subject: Reply with quote

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
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Sat May 01, 2004 3:55 pm    Post subject: Reply with quote

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
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Thu May 20, 2004 4:38 am    Post subject: Properties Reply with quote

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.

Code:

/*! Class Foo
 * Some descriptive text
 */
class Foo
: Base
{
mixin Bar; // provides XYZ functionality

  /*! Property bar
   * Some descriptive text
   */
  private int _bar;
  // get
  public int bar()
  {
    return _bar;
  }
  // set
  public void bar(int x)
  in {
    assert(x >= 0 && x < 1024);
  }
  body {
    _bar = x;
  }

public:

protected:

private:

}


So basically the new style is:

  1. Documentation comment
  2. 'class XXX'
  3. Base class and/or interfaces on next line
  4. {
  5. Mixins, with trite comment -- not indented
  6. Static Constructor
  7. Static Destructor
  8. Static Properties
  9. Non-Static Properties
  10. Invariant (if present)
  11. Public section
  12. Protected section
  13. Private section
  14. }
  15. Unit-tests (if present)


Properties should take the format:

  1. Documentation comment
  2. private-access storage
  3. public-access gettors
  4. public-access settors


All sections:

  1. Constructors (if present)
  2. Destructor (if present)
  3. Static fields/variables
  4. Static methods
  5. Non-static fields/variables
  6. Non-static methods

_________________
Chris Nicholson-Sauls
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
kris



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

PostPosted: Thu May 20, 2004 11:10 am    Post subject: Re: FIXMEs Reply with quote

larsivi wrote:
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.

Doxygen has a nice @todo tag that gathers related documentation onto a distinct html page ...
Back to top
View user's profile Send private message
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Mon May 31, 2004 3:55 am    Post subject: identifiers Reply with quote

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:

Code:

int a,
     b;
float x,
       y;
ExampleFrameListenerManager eflm;


actually, writing

Code:

int a;
int b;


might be cleaner at that.
Back to top
View user's profile Send private message
csauls



Joined: 27 Mar 2004
Posts: 278

PostPosted: Thu Jun 17, 2004 2:41 pm    Post subject: Reply with quote

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
Back to top
View user's profile Send private message AIM Address Yahoo Messenger
Display posts from previous:   
Post new topic   Reply to topic     Forum Index -> Sinbad All times are GMT - 6 Hours
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group