- in general, you need to read the documentation of all the bases
classes of a class and the module before you will understand the
class. I think this cannot be reasonably avoided.
Agreed
ConfigurationSetRMSDMetric would make more sense in light
understanding statistics::Metric. For example, it has no get_rmsd()
method since it is a specialization of the Metric base class and that
defines a get_distance() virtual method, so having a get_rmsd() method
would be useless where it is supposed to be used.
- What I would really like to see is that when someone spends the
time to figure something out like this, they add an example/patch the
comments in the files and then sends the patch off to someone to
integrate :-)
I wouldn't like to see any of these situations. If functions were
documented (by the writer), the user wouldn't have to figure out
anything or write patches. I agree with Riccardo also, a lot of
functions in IMP (mine included) are cryptic, or require some knowledge.
- I'd like to move to a more structured commit model for IMP with some
more review of things that go in so that we can prod people (and me)
more to improve docs/merge redundant things. I typed up some thoughts
on modifying the comment model here
<https://github.com/salilab/imp/wiki/A-proposed-commit-model-for-IMP>
Feel free to edit (or request permissions to edit, I'm a bit unclear
on how those are regulated :-) The main idea would be that if things,
in general, have two people look at them before going into most
modules in IMP, they should be a bit more coherent and documented.
And, if one is able to share things prior to committing them to the
SVN repository, they can stay in purgatory a bit longer (and will
hopefully be worked on a bit longer), before they considered good
enough and work on them ceases (as tends to happen). Not sure if this
will work :-)
Just a practical comment o this. If were are going to do all these
changes, please let's switch to git as soon as possible. Learning
another tool (git-svn or git flow) that is just an intermediate solution
is a mess and has problems: For example, I talked to Ben and Daniel
about moving developments not in the main repository between computers
(mine and the cluster) and the options were suboptimal (use private git
repositories, deal with github ...). I tried to use them anyway, and I
just gave up because of the commit hooks: