wxdevide-devs

[Wxdevide-devs] Coding Guidelines

[<so...@ti...>]

I have posted a basic guide on the wiki with the contents of 
discussions so far. To get more feedback on the guidelines I have a 
list of other projects guidelines. I particularly like some of the 
ideas of the NOX project.

http://pim.kde.org/development/coding-korganizer.php
http://developer.gnome.org/doc/guides/programming-guidelines/code-
style.html
http://trilinos.sandia.gov/packages/docs/r4.
0/packages/nox/doc/html/coding.html

Sof.T




See your new look Tiscali Homepage - http://www.tiscali.co.uk

___________________________________________________

Re: [Wxdevide-devs] Coding Guidelines

[Tony R. <tb...@gm...>]

That's a nice start. I'd like to add:

C++ header files end in .H and source files end in .Cpp

Each file should begin with the $Id tag, original author, and license tag

Every include file must contain a mechanism that prevents multiple
inclusions of the file. For example, the following should follow the header
information for the NOX_Abstract_Vector.H header file.

#ifndef NOX_ABSTRACT_VECTOR_H
#define NOX_ABSTRACT_VECTOR_H

*...body of include file goes here...*

#endif


If the arguments of a function don't fit into the 80 chars, start a new line
and align the additional arguments with the first one.

For if, else, while and similar statements put the brackets on the same line
as the statement (this makes it easier to see if the IDE has a matching
braces tool)

Each public function must have a Doxygen compatible comment in the header

Use true and false instead of TRUE and FALSE.

-Tony




On Thu, Oct 2, 2008 at 12:55 PM, so...@ti... <so...@ti...>wrote:

> I have posted a basic guide on the wiki with the contents of
> discussions so far. To get more feedback on the guidelines I have a
> list of other projects guidelines. I particularly like some of the
> ideas of the NOX project.
>
> http://pim.kde.org/development/coding-korganizer.php
> http://developer.gnome.org/doc/guides/programming-guidelines/code-
> style.html<http://developer.gnome.org/doc/guides/programming-guidelines/code-style.html>
> http://trilinos.sandia.gov/packages/docs/r4.
> 0/packages/nox/doc/html/coding.html<http://trilinos.sandia.gov/packages/docs/r4.0/packages/nox/doc/html/coding.html>
>
> Sof.T
>
>
>
>
> See your new look Tiscali Homepage - http://www.tiscali.co.uk
>
> ___________________________________________________
>
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge
> Build the coolest Linux based applications with Moblin SDK & win great
> prizes
> Grand prize is a trip for two to an Open Source event anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
> _______________________________________________
> Wxdevide-devs mailing list
> Wxd...@li...
> https://lists.sourceforge.net/lists/listinfo/wxdevide-devs
>

Re: [Wxdevide-devs] Coding Guidelines

[Malcolm N. <m.n...@wa...>]

On 03/10/2008 02:16, Tony Reina wrote:
> That's a nice start. I'd like to add:
>
> C++ header files end in |.H| and source files end in |.C|pp

Agreed.

>
> Each file should begin with the $Id tag, original author, and license tag

Agreed, I'll go through the current source and add them.

>
> Every include file must contain a mechanism that prevents multiple 
> inclusions of the file. For example, the following should follow the 
> header information for the |NOX_Abstract_Vector.H| header file.
> #ifndef NOX_ABSTRACT_VECTOR_H
> #define NOX_ABSTRACT_VECTOR_H
>
> /...body of include file goes here.../
>
> #endif
>    

Agreed.

>
> If the arguments of a function don't fit into the 80 chars, start a 
> new line and align the additional arguments with the first one.
Agreed. I think  this might be done with |--indent-preprocessor or 
||--max-instatement-indent=# |but 'm not sure. We'll have to do some 
experimentation I think.

>
> For if, else, while and similar statements put the brackets on the 
> same line as the statement (this makes it easier to see if the IDE has 
> a matching braces tool)

You want

    if ( /*Something*/ ) { //YES
      i++;
      j++;
    }


Here is the first stumbling block

I much prefer

    if ( /*Something*/ ) // Yes!
    {
      i++;
      j++;
    }


I much prefer to see the braces, and you can still check if the brace 
matcher works. Now let's see. You live in America, I live in the 
Netherlands, is there a boat somewhere in the Pacific with a decent bar?

Of course this is trivial and can be achieved by having two astyle 
config files, a global one for the svn code, and a local one for the 
working copy, we just have to enforce the svn config file before a merge 
and cpomit. Your local one can be what you want.

>
> Each public function must have a Doxygen compatible comment in the header

Agreed.

>
> Use true and false instead of TRUE and FALSE.
>

Agreed.

Best regards
Mal

Re: [Wxdevide-devs] Coding Guidelines

[Tony R. <tb...@gm...>]

> > For if, else, while and similar statements put the brackets on the
> > same line as the statement (this makes it easier to see if the IDE has
> > a matching braces tool)
>
> You want
>
>    if ( /*Something*/ ) { //YES
>      i++;
>      j++;
>    }
>
>
> I'm willing to concede the point to you.

 The reason I prefer it the former way is because on the trailing bracket,
it is often hard to tell which starting bracket it goes with. For example,

if (Something) { //YES

if (SomethingElse) {

if (SomethingOther) {

... lots of lines of code, many with other embedded brackets...

}

}

} // END YES


If there are, say, 3 or 4 embedded if-then brackets, it may be hard to tell
what the  //END YES bracket goes with. In many IDEs, however, there's a
brace matching tool which shows the matching brace in the command line. In
my case, it would show:

if (Something) {YES

in your case, it would show:

{

So I'm just pointing out that in my style you get more info on the matching
brace.

Perhaps a happy medium would be to use your method, but require developers
to add comments to their braces (both beginning and end).

e.g.

if (Something) // YES
{ // Begin "if (Something)"

... code ...

} //End "if (Something)"


-Tony

Re: [Wxdevide-devs] Coding Guidelines

[Malcolm N. <m.n...@wa...>]

On 03/10/2008 07:15, Tony Reina wrote:
>
>     > For if, else, while and similar statements put the brackets on the
>     > same line as the statement (this makes it easier to see if the
>     IDE has
>     > a matching braces tool)
>
>     You want
>
>        if ( /*Something*/ ) { //YES
>          i++;
>          j++;
>        }
>
>
> I'm willing to concede the point to you.

What's wrong? Don't like Southern Comfort? :)
>  The reason I prefer it the former way is because on the trailing 
> bracket, it is often hard to tell which starting bracket it goes with. 
> For example,
> if (Something) { //YES
> if (SomethingElse) {
> if (SomethingOther) {
> ... lots of lines of code, many with other embedded brackets...
> }
> }
> } // END YES
> If there are, say, 3 or 4 embedded if-then brackets, it may be hard to 
> tell what the  //END YES bracket goes with. In many IDEs, however, 
> there's a brace matching tool which shows the matching brace in the 
> command line. In my case, it would show:
> if (Something) {YES
> in your case, it would show:
> {
> So I'm just pointing out that in my style you get more info on the 
> matching brace.

What tool does it this way? I'd like to take a look.

I understand what you're saying here, but  if my style was enforced, 
(and this is purely personal opinion here) when viewing the source with 
several embedded if then stuff


if (some condition)
{
     if (some other condition)
     {
         if (yet another condition)
         {
         }
     }
}

and the reader only has to follow the brace up or down to find the 
associated brace and or condition.

Unfortunately wxDev at the moment only highlights the brace itself, 
which is unfortunate, since I can see the advantage of highlighting the 
complete line including condition. By the way, have we changed the brace 
highlighting code anywhere? I  can remember that the matching braces 
were highlighted in inverse video at some point, which made them easier 
to see, but currently the matching brace is simply bolded. Or is this 
something quircky on my end? Or am I getting confused with another ide?

> Perhaps a happy medium would be to use your method, but require 
> developers to add comments to their braces (both beginning and end).
> e.g.
> if (Something) // YES
> { // Begin "if (Something)"
> ... code ...
> } //End "if (Something)"


I can go along with this, although I can see the code getting crowded, 
unless we enforce a wide space (say 3 tabs worth) between the brace and 
the comment.

if (Something) // YES
{             // Begin "if (Something)"
... code ...
}             //End "if (Something)"

I was once pointed to an "elastic tabs"idea once, the idea being that 
all tabs were lined up, and not just at the 4 char boundary. 
http://nickgravgaard.com/elastictabstops/
That looked interesting, I wouldn't mind seeing that in the ide.

Best
Mal

Re: [Wxdevide-devs] Coding Guidelines

[Tony R. <tb...@gm...>]

>
>
> I was once pointed to an "elastic tabs"idea once, the idea being that
> all tabs were lined up, and not just at the 4 char boundary.
> http://nickgravgaard.com/elastictabstops/
> That looked interesting, I wouldn't mind seeing that in the ide.
>
>
Actually, when I read "elastic tabs" I immediately thought of code folding.
As long as we have code folding when we are coding, then my point is moot.
The developer just needs to fold the code and the stuff in between is
hidden. So it won't be hard to figure out in that case.

Nothing to see here, move along...

-Tony

Re: [Wxdevide-devs] Coding Guidelines

[Esteban A. B. <nab...@ya...>]

By the way, have we changed the brace 
highlighting code anywhere? I  can remember that the matching braces 
were highlighted in inverse video at some point, which made them easier 
to see, but currently the matching brace is simply bolded. Or is this 
something quircky on my end? Or am I getting confused with another ide?Yes, I remember that too. Was that the scintilla stuff? Maybe we can enable it just in time for RC3 next week, along with the rest of the late minute fixes.


      ____________________________________________________________________________________
Premios MTV 2008¡En exclusiva! Fotos, nominados, videos, y mucho más! Mira aquí http://mtvla.yahoo.com/

Re: [Wxdevide-devs] Coding Guidelines

[Malcolm N. <m.n...@wa...>]

On 02/10/2008 21:55, so...@ti... wrote:
> I have posted a basic guide on the wiki with the contents of
> discussions so far.
What about component naming? Obviously the components have inherited 
their Delphi names but should there be a list of components and their 
"accepted" names? At the moment it is not important, but I envisage us 
continuing development, perhaps adding new dialogs, and these should 
follow the naming conventions for the rest of the project.

While we are on the subject, should this be something we should add to 
wxdev-c++ initially? Offering a cbTemp1 instead of WxCheckBox1?


> To get more feedback on the guidelines I have a
> list of other projects guidelines. I particularly like some of the
> ideas of the NOX project.
>    

I would insist on changing

Braces ("{}") which enclose a block should be aligned as follows:

    if ( /*Something*/ ) // Yes!
    {
      i++;
      j++;
    }

    if ( /*Something*/ ) { // Okay
      i++;
      j++;
    }

    if ( /*Something*/ ) // No!
      {
        i++;
        j++;
      }

to

Braces ("{}") which enclose a block should be aligned as follows:

    if ( /*Something*/ ) // Yes!
    {
      i++;
      j++;
    }

    if ( /*Something*/ ) { // No!
      i++;
      j++;
    }

    if ( /*Something*/ ) // No!
      {
        i++;
        j++;
      }

That is

    if ( /*Something*/ ) // Yes!
    {
      i++;
      j++;
    }

should be the only acceptable form. Once we use Astyle then I think this is|--style=ansi

Further Astyle options

||--indent=tab=4 // indent using tabs, and each tab is 4 spaces|
|--brackets=break //should be covered in --style=ansi|produces the effect above

|--indent-classes
||--indent-switches
||--indent-namespaces
||--indent-labels
||--indent-preprocessor
||--max-instatement-indent=40
||--pad=paren


I'm not sure if I've missed anything important. We do need a config file 
for our use, so we only need to call astyle on the file itself. I had 
astyle as a tool in wxdev once, so it is certainly possible to use 
within the ide.

Could I also suggest that developers keep two verions of the code on 
their systems? One which is a local copy of the svn head, and the second 
which is the actual work in progress copy. All changes should be 
transferred from the working copy to the svnhead copy before updating 
svn. This way we should be able to prevent updates to form files when 
all that has changed is the position of a component (unless that 
position/size change is warranted). We all know that to have the code 
generated we need to change something, and the easiest is to move a 
component, but that change doesn't have to be returned to svn.

Also (and unfortunately we don't seem to be able to do this currently) 
we need to have the designer place dialogs in a subdirectory. So for 
example the base directory should have all necessary files and the main 
form files, but that each dialog thereafter should be placed in its own 
folder. Thus each folder would contain three files (not yet decided 
about the xrc files) the .cpp/.h/.wxform files. Unfortunately I don't 
seem to be able to do this at the moment, but would like to see it 
happening.

I'll probably think of something later, but these are my initial thoughts.

Best regards
Mal
|

Re: [Wxdevide-devs] Coding Guidelines

[Tony R. <tb...@gm...>]

> What about component naming? Obviously the components have inherited
> their Delphi names but should there be a list of components and their
> "accepted" names? At the moment it is not important, but I envisage us
> continuing development, perhaps adding new dialogs, and these should
> follow the naming conventions for the rest of the project.
>
> While we are on the subject, should this be something we should add to
> wxdev-c++ initially? Offering a cbTemp1 instead of WxCheckBox1?
>

Yes, I think it's a good idea to convert the names and formatting now.


>
> > To get more feedback on the guidelines I have a
> > list of other projects guidelines. I particularly like some of the
> > ideas of the NOX project.
> >
>
> I would insist on changing
>
> Braces ("{}") which enclose a block should be aligned as follows:
>
>    if ( /*Something*/ ) // Yes!
>    {
>      i++;
>      j++;
>    }
>
>     if ( /*Something*/ ) { // Okay
>      i++;
>      j++;
>    }
>
>    if ( /*Something*/ ) // No!
>      {
>        i++;
>        j++;
>      }
>
> to
>
> Braces ("{}") which enclose a block should be aligned as follows:
>
>    if ( /*Something*/ ) // Yes!
>    {
>      i++;
>      j++;
>    }
>
>     if ( /*Something*/ ) { // No!
>      i++;
>      j++;
>    }
>
>    if ( /*Something*/ ) // No!
>      {
>        i++;
>        j++;
>      }
>
> That is
>
>    if ( /*Something*/ ) // Yes!
>    {
>      i++;
>      j++;
>    }
>
> should be the only acceptable form. Once we use Astyle then I think this
> is|--style=ansi
>
> Further Astyle options
>
> ||--indent=tab=4 // indent using tabs, and each tab is 4 spaces|
> |--brackets=break //should be covered in --style=ansi|produces the effect
> above
>
> |--indent-classes
> ||--indent-switches
> ||--indent-namespaces
> ||--indent-labels
> ||--indent-preprocessor
> ||--max-instatement-indent=40
> ||--pad=paren
>
>
> I'm not sure if I've missed anything important. We do need a config file
> for our use, so we only need to call astyle on the file itself. I had
> astyle as a tool in wxdev once, so it is certainly possible to use
> within the ide.
>

Agreed. I don't have any problems with these guidelines. The major thing is
to have an Astyle config file in SVN with these settings so that a developer
just has to remember to "astyle.exe -f wxdevide.config *.*" before
committing changes to SVN.


>
> Could I also suggest that developers keep two verions of the code on
> their systems? One which is a local copy of the svn head, and the second
> which is the actual work in progress copy. All changes should be
> transferred from the working copy to the svnhead copy before updating
> svn. This way we should be able to prevent updates to form files when
> all that has changed is the position of a component (unless that
> position/size change is warranted). We all know that to have the code
> generated we need to change something, and the easiest is to move a
> component, but that change doesn't have to be returned to svn.
>

I see your point here, but it's a little difficult logistically to do this.
I think what I might try is to keep two SVN directories, one called "MyCopy"
and one called "SVN_HEAD". Both will be linked to SVN HEAD, but (hopefully)
if I try to commit changes from MyCopy I'll catch the mistake beforehand. (I
wonder if there's a way to make Tortoise ignore my changes in the MyCopy
directory and just look for updates in SVN?) Otherwise, I can easily see the
MyCopy directory become out of sinc with other developers commits to SVN.


>
> Also (and unfortunately we don't seem to be able to do this currently)
> we need to have the designer place dialogs in a subdirectory. So for
> example the base directory should have all necessary files and the main
> form files, but that each dialog thereafter should be placed in its own
> folder. Thus each folder would contain three files (not yet decided
> about the xrc files) the .cpp/.h/.wxform files. Unfortunately I don't
> seem to be able to do this at the moment, but would like to see it
> happening.
>

You mean for both our source code and for the way the IDE behaves? So, for
example, the About dialog box in our source code will be place in a
subdirectory called "AboutFrm"? I suppose that makes sense (although it will
create a massive number of subdirectories).

One thing I thought of in regards to dialogs: We should build the filename
for the .h, .cpp, and .wxform into the class definition for the dialog. I
think right now we are always assuming that all 3 files will have the same
prototype name (e.g. AboutFrm.cpp, AboutFrm.h, AboutFrm.wxform). So it's
hardcoded that a .wxform file called AboutFrm.wxform will always try to
modify code in files called AboutFrm.cpp and AboutFrm.h. It would be nice to
be able to generalize this in case a user every wanted to rename the files.

-Tony

-Tony

Re: [Wxdevide-devs] Coding Guidelines

[Malcolm N. <m.n...@wa...>]

On 05/10/2008 22:33, Tony Reina wrote:
> Agreed. I don't have any problems with these guidelines. The major 
> thing is to have an Astyle config file in SVN with these settings so 
> that a developer just has to remember to "astyle.exe -f 
> wxdevide.config *.*" before committing changes to SVN.
>

This would be a single batch file containing

astyle.exe -f wxdevide.config *.cpp
astyle.exe -f wxdevide.config *.h

If you do *.* it will also look at the .wxform files and seriously screw 
them up.

Mal

Re: [Wxdevide-devs] Coding Guidelines

[Tony R. <tb...@gm...>]

>
>
> If you do *.* it will also look at the .wxform files and seriously screw
> them up.
>
>
Sure that makes sense.

Although, wxform files are really just Delphi files. I was thinking that we
would be trying to move the designer file format to something like XML (i.e.
the XRC format). If we use XRC for the format, then we could potentially
have a method for exporting/importing designer forms to/from other IDEs.

-Tony