[mythtv] mythtv- code architecture

[Daniel Kristjansson]

On Wed, 2007-06-13 at 17:07 -0400, David Asher wrote:
> I've been thinking of making some patches which are just comments for
> the code to document what (little) I am able to figure out.  How large
> would you want the patches?  I know generally smaller is better for
> actual features, so that review is not too painful.  Would the same
> thing be true for comments?  I suppose I could open a single ticket
> and attach many small patches to be reviewed in bite-sized chunks as
> time permitted.  My fear is that I'll be WRONG about the conclusions
> I've come to, so I don't want them checked in without being read over
> by someone with actual understanding of the code.

Don't worry I'll read over them before committing them.

A dozen files at a time per patch is fine if you are
documenting something like the audio subsystem. But if
you are documenting a large file, or a file that changes
frequently, do a patch per file. The goal is to have as
few rejects as possible. With documentation patches this
isn't as essential because a missing piece of documentation
isn't going to break any functionality, but it does mean
some additional work. A tracking ticket is a good idea.

Also, documenting parameters or how a method works is usually
not very important. Documenting what classes do and how
to use them, relationships between classes, and how to use
complicated methods method are important. Basically, if you
don't need the documentation to understand something new to
you, probably no one else does either, if you do, someone
else may also benefit from it.

-- Daniel