|
From: Paulo E. C. <pau...@gm...> - 2013-04-21 11:57:43
|
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
|