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
_______________________________________________ mythtv-dev mailing list [EMAIL PROTECTED] http://mythtv.org/cgi-bin/mailman/listinfo/mythtv-dev
