Re: [FreeWRL-develop] Codebase port to c++?

[Paulo E. C. <pau...@gm...>]

tl;dr - Rant ahead, sarcastic comments, positive suggestions ...

I've been a subscriber to the mailing list since 2011 though I've trying 
to play with freewrl for longer...

And every so often I peek into the folder where the emails end up...

This time it was the codebase port to c++ email that caught my eye... I 
read the thread and decided to look at the code.

I cd into the project dir where I have my gitted CVS version and I pull 
all the changes from trunk integrating them in my git repository version 
of freewrl.
Whilst I blink my eyes I create a test branch and based on my own 
personal branch and I rebase trunk/master onto it.
What I get is,the latest trunk with my commits on top of it just as if I 
had written them just now.
My commits are just notes, my build scripts, and some examples I've 
collected here and there...

Every so often I try to go for a build...
Most of the times a straight build from trunk fails...

But this time I was feeling more energetic and decided to investigate 
matters.

I soon found issues with the build ....
And then I remember what I've noticed some time ago, that, though I know 
what it does, the code seems rather convoluted and complex to fully 
understand.

Then I wish that there could be some guiding doc just explaining the 
contents of each dir and briefly detailing how all the pieces fit together.
Something condensed in a single place rather then being scattered in the 
code and in the website ...

I also wish there were some tests so that I could at least understand 
what is the behaviour and response that you are hoping for the given 
parts of the whole beast.

Anyway, I put all those thoughts momentarily aside and decided to take 
the code for a build spin ...

Make blows up straight away after configure and friends had run.
I dig in the code, and I remember what I had forgotten, because every 
time I look at it it's as if it is the first time ...

Gigantic files, stale code, hardcore C, gigantic functions with no 
comments sprinkled with preprocessing directives and commented code to 
keep all your brain registers in supercharge.

A couple of greps and some opened files later and I got it....

0001-Make-it-build-0.patch

I try again and boom...

0002-Make-it-build-1.patch

I try going for it again .... Cross fingers harder !!! Boom

0003-make-it-build-2.patch

Last try.... and Finally.... Success!
And after a couple of builds to make sure I had it right, it was only 
taking me 2m10s to build the whole thing.
Thank the gods for ccache.

Those patches are just blunt fixes in order to get the thing to build. 
I'm not sure how good or ideal they are...

Wrapping thoughts...

It seems like you're using your trunk as a staging area for experiments 
whilst sharing code/ideas amongst yourselves or similar.
That's ok and it could be seen as the purpose of a sharing code system 
but not the role of a Version Control System.

Your trunk should ideally always be in a buildable condition.
For code sharing and development and testing there's branches.

I would like to help a bit more if it was easier for me to help.
And that's exactly the purpose of this rant to try to bring some 
external perspective of how I perceive things to be.
This means that If I see them like this, chances are many more 
people/newbies will see them as well.

And for someone who's looking at the code for the first time, I suppose 
it can be demoralizing if every time you try to have a go at it it fails.
And you try to find some understanding to how it all fits together and 
there's none or it is so scattered that it is easy to loose track of it.

</rant over>

Sometimes you need a step back in order to be able to take two forward...

I decided to write a wishlist of things I think would help me help you 
next time I have a look at the project...

<WishList>

- Documentation briefly ( optionally as comprehensive has possible ) 
describing the contents of each directory.
   - How do they work together
   - Perhaps enable the sourceforge wiki and condense information there ?

- A strategy to start documenting what each function is supposed to do.
   - Start with the more meaty ones
   - Consider the Doxygen format perhaps ?
   - If you're amending a function/method and you're familiar with what 
it does, consider adding some notes at the beginning disclaiming in/out 
and expected behaviour

- Some contextual explanation of the purpose of the codegen/ folder and 
how to run it.
   - Why it exists
   - What it generates and why
   - How it runs... it seems you're suppose to pipe something into perl 
-MVRMLC ? Is that written somewhere ?
   - How do you validate that it's producing the right thing ?
   - I gather that VRMLC is generating some c,h files but my bet is, 
from looking at it, that maintaining it and extending it is super hard.
     - If one understands the exact role of these files, higher are the 
chances of being able to refactor them into more easily extendible code.
     - How could one test the result of this codegen process ?

- How do you test the resulting build ?
   - Assuming you couldn't run freewrl after a build, what would be 
important to validate as correct behaviour, expected Input/Output ?
   - What is really important in terms of what you are implementing ?

- Consider moving to at least SVN preferably Git|Mercurial
   - CVS is old, cumbersome and hard to enable collaboration of multiple 
people, basically everything is hard with CVS...

- Consider some cleaning
   - VRMLC.pm has 500 lines of revision logs in it. That's why VCS 
exist. These need not be in the file.
   - Consider doing the same for all the other files in the same situation.
   - Remove unnecessary trailing whitespace in lines. Standardizing this 
helps with future merges and overall diff comprehension and readability
      - Editors can be configured to have this removed automagically
   - Remove old commented legacy code. Make a note for it on the commit.
   - Have a debug flag or preprocessing to enable the output of all 
those commented printfs that are really important to see when things get 
hairy.

- Coding
   - Some coding guidelines ?
   - 4 space indentation ? Other ?
   - New code has to have some brief documentation ?

- Roadmap
   - Where is the project heading
   - How much of the X3d/VRML7 spec is the project interested in 
covering/implementing
   - etc ...

</WishList>

I have extensive experience integrating different components and writing 
Modern Perl code.
My C/C++ skills are a bit rusty but I can get along fine.
I don't have much time in my hands but every so often I do enjoy a 
detour into playing with something like FreeWRL.
If every such time I could make a positive contribution albeit small I 
supposed that everyone would win ...


Hoping this is seen as positive feedback...



                 PECastro