[mythtv] MythTV: Isaac Tivo: > 100 tech guys

[Colin Guthrie]

Ed Wildgoose wrote:
> However, can we agree on the best way to do it first?  I think
> doxygen (is that right now?) might be a promising move?  I would
> prefer to get a steer from Isaac first though on how we are going to
> do this going forward.

I would thoroughly recommend Doxygen as a tool. I've used it in quite a
few C++ projects before and find it invaluable when working in a team.
If you've only got a small project then it's a bit overkill, but with,
and I quote ">100 other people who make it possible" working on Myth and
trying to hack the source to make it better, more efficient, more
featurful and less buggy!

I even use Doxygen on my PHP projects now too (some of which are pretty
huge), and it works like a charm. It has it's bugs too, but nothing too
crazy and it can usually be worked around. I think the C++ doc
generation side is far more stable than the PHP tho', as I don't recall
any major issue when using it a couple of years ago for that!

Having also recently hacked about with MythMusic (and another patch 
coming soon), I have to concur with Ed Wildgoose that class inheritence 
diagrams would have been great. And more detailed documentation of the 
sometimes bizarrly named variables would be good too. Class inheritence 
can be generated just by firing up doxygen, but it only really comes 
into it's own with structured comments.

My recent Metadata patch probably had a few doxygen comments in the new 
classes I created. I almost do this automatically when I write code now, 
and I actually meant to strip them out before supplying the patch (as I 
thought they had been previously frowned upon), but forgot!

> Isaac: Final word?

I don't want to speak out of turn or on Isaac's behalf, but IIRC the 
main issue was that Doxy comments can be quite large and take up a fair 
amount of screen real estate when editing your code.

I agree but I feel that the benefits far outweigh this disadvantage. 
I've just started using Eclipse as my IDE for development and the CDT 
project for C/C++ development has many useful functions.

IIRC, I think it does block comment folding, which means that it can 
basically turn a 10 line comment into a single line with a little + next 
to it. Perhaps using and IDE/Editor with such capabilities would work 
round that objection for many people?? (I know Eclipse can be 
slow/buggy, but there are others with similar features I'm sure, and 
Eclipse seems mostly fine for me).


Of course, if Doxygen was adopted, there would be the question of which 
style of commetns to use!! I've used both Qt style and JavaDoc style, 
and switched from one to the other at one point to get round indentation 
bugs in XEmacs!!! Seeing as Myth is Qt based I sps it makes sense to use 
Qt style!

As a companion to this, would some formal, written-down coding standards 
be a good idea? We had some a while back that were really good. It 
covered things like class named (TitleCaseNoUnderscores), local 
variables (lower_case_underscores), member variables 
(mTitleCasePrefixedWithM), and method/function arguments 
(titleCaseInitialDropCap) etc. etc. It made development very easy. At 
the moment when I read stuff in MythMusic, it is sometime hard to know 
at a glance with variables are local ones, which are member variables 
etc., so when working on large projects with multiple developers this 
can be a godsend!

I can't find the original file we used, but a quick look at this:
http://www.possibility.com/Cpp/CppCodingStandard.html and it seems to 
fit what I usually do. I especially like " 6 Phases of a Project (joke)" 
and " Flow Chart of Project Decision Making (joke)" but the real info 
starts at section 3.

I'm not suggesting everything gets changed to conform, just that there 
is a clear strategy for going forward. If someone wants to apply this to 
existing code then fine, but perhaps they can make their change using 
e.g. a sed script that then gets posted onto the mailing list along with 
their patch to let people with other, uncommited patches easily update 
their code!!

Perhaps I'm throwing too much in the melting pot here? One step at a 
time is probably better.

I vote for Doxygen.

All the best and thanks for everyones' efforts.


Col.

-- 

+------------------------+
|     Colin Guthrie      |
+------------------------+
|  myth at colin.guthr.ie   |
| http://colin.guthr.ie/ |
+------------------------+