I agree with all of the above, both the suggestion for a coding standard
and some structured comments in the code that we can extract on demand
to build the documentation.
I have a hard enough time getting people to just use 4 space indents. I don't see random contributors following a coding standards guide at all.
Part of the problem could be that we don't know that there is a 4 space rule... I tend to just have a look at the code I am editing to see the style and try to follow that, but I am migrating to linux from the windows world and never seem to have the time to read the vim manual and find out how to set it to use spaces instead of tabs. So in my case you are changing all my tabs for me because I am "too stupid" to read the manual and figure this stuff out for myself
However this is exactly the kind of thing that I probably would look up if there was a condensed coding standards page which pointed this stuff out...?
I really DON'T think that a 20 page set of guidelines is called for, but how about 10 bullet points on tab spacing, file naming, class naming, variable naming and required commenting? At the bottom put down the .vimrc or emacs config required to make this happen?
Someone else pointed out that it's possible to put the vim config files in the myth source so that this happens automatically. I'm aware it's possible but not how to set this up (or I would have done already).
Anyone want to have a stab at the top 10 Dos and Don'ts?
Here's my suggestion on variable naming:
1) Variable Naming: Make 'em left to right specific. The idea is that related variables should sort together alphabetically, ie
audioVolLevel audioId audioMutex VideoTimeRemaining VideoSomethingElse
Variable names should be compact, but also descriptive. Try to make them self explanatory
Description of their use and purpose should accompany the declaration. For class variables a rough outline of how they fit into the algorithm should be given and any assumptions or notes on valid ranges should be given
blah, blah
As I've said before, I don't mind someone adding doxygen comments, as long as they don't take up too much space or otherwise get in the way. This means a few lines per comment, max.
I haven't used doxygen, but wouldn't the comments go in the header files? I personally prefer header files which are fully documented and form the basis for understanding the module, and the code files to be fairly clean. I find it useful then to leave the header files open in one screen for reference while working on the code.
Basically it's just as you said. For comments you want them all closely spaced and for code you don't want too many comments in the way.
If this is not possible with doxygen then is there another better system?
I hope that we are getting close to some useful conclusion here...
Ed W _______________________________________________ mythtv-dev mailing list [EMAIL PROTECTED] http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
