Thanks for your input Jeff. I am trying to keep this as simple as I
possibly can.
> I gather you are saying you want to require consistency...
For sure! As a developer (even as a human being), consistency helps one
sleep at night.
> but wait... "makes sure that the rationale document has been
> altered" ? I'd think it would be too involved to determine
> whether the developer has added useful information
Good point. One can only go so far to second guess what a developer is
going to put inside one of these rationale documents. I would imagine in
time that as a development initiative grew, and a development team got
large enough, one would want to maintain some type of branch system
where a team leader had the responsibility to review what a developer
put in to the rationale before merging a developer's branch in to the
code base.
But I'm sure you know this too...
> I see that you agree now that subversion itself doesn't
> need a new feature. In fact, you are just defining your own
> company policy. That's fine.
That's right. Being new to Subversion, I started this thread under the
assumption that I lack knowledge about its existing features and
continue to hold that assumption. I'm trying to capitalise on what there
is, and I wish to add as little as necessary to make it do what I want.
> Yes, I do have this "rationale" documentation that you talk
> about. The documentation is streamlined into my project source
> code. It's called "comments".
Yes, I understand what you're driving at. However, there is a layer of
information - the individual module's development history - that while
very relevant to the continued maintenance of a code base, is
inappropriate for inclusion in comments. Tools like Javadoc have been
around for a long time, and do a very good job at producing
documentation relevant to using the API of a java package and whatever
else Javadoc might be able to do to make a product easier to use. I have
used it, and see that it is good for documenting the API.
In saying that, the minutia of a module's development history does not
belong in Javadoc, and also, I believe, does not belong in code comments
for two reasons: no single user of a product is the slightest bit
interested in the development history of the products implementation;
and I thoroughly detest wading through line upon line of documentation
just to find the piece of code that I'm after. What a distraction!
I believe that recording this history is beneficial to the pursuit of
stress-free development, especially when, for whatever reason, the
module subject to change has no facility to record comments. I have
worked in an organisation who's only respect to module change history
was a very long set of comments at the start of a code module. Remove
the comments, and reducing the module size by 20% was not uncommon.
As a bit of anecdotal information, the code base I mention above was
maintained by a team of about twenty people, but was not even subject to
version control. Ultimately, I resigned, thinking how glad I was to get
out of that house of cards. It was not a Java development, and it was on
a mainframe environment.
Respectfully,
Owen.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Fri Jan 12 02:42:54 2007