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

[Jeremiah Morris]

On 9 Dec 2004, at 4:48 AM, Colin Guthrie wrote:

> 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.

I completely agree here.  In the mysql.txt bootstrapping patch, Nigel 
and I had a few arguments over style, where there was equal precedent 
for either position.  No matter which way we coded things, it was going 
to look out of place.  I would happily put together cleanup patches for 
the existing code if we formally said which way is the Right Way.

On generated documentation: I've never used Doxygen, but I have found 
Javadoc to be invaluable on a few medium-scale projects.  Our team was 
pressed for time and building a prototype, so we didn't spend any extra 
commenting time, but the docs were still a big help.  If a method was 
self-evident, we didn't use a Javadoc comment; but if there was a 
"gotcha" to be noted, it was easy to put it in.  We generated the docs 
nightly, and it saved us loads of time that would otherwise be spent 
crawling through the sources to find the inheritance tree or the syntax 
for an obscure method.  In the cases where something wasn't obvious 
("width must be a power of 2"), it stood out nicely in the HTML 
listing.

My point is, generated documentation and over-commenting are orthogonal 
issues; having a documentation style doesn't imply that one needs to 
state the obvious for every variable.  I think Isaac's point is that 
good code needs little documentation, and the availability for extra 
comments shouldn't be an excuse for poor naming conventions or obtuse 
design.  I agree, but in practice even the best designs often need to 
give a bit of an overview or call special attention to the  occasional 
wrinkle, which is where the documentation can lend a hand.  It's like 
having a style guide; if the format of the comment is fixed, the 
programmer is free to write it, rather than worrying about what it 
should look like.  If we use the documentation to fit our needs, rather 
than hiding the source within layers of documentation (no offense to 
literate programming), we can have the best of both worlds.

- Jer