This week's book giveaway is in the Jobs Discussion forum.
We're giving away four copies of Customer Requirements for Developers and have Marcho Behler on-line!
See this thread for details.
The moose likes IDEs, Version Control and other tools and the fly likes Your local Versioning best practices Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Customer Requirements for Developers this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Engineering » IDEs, Version Control and other tools
Bookmark "Your local Versioning best practices" Watch "Your local Versioning best practices" New topic

Your local Versioning best practices

Matt Kidd
Ranch Hand

Joined: Jul 17, 2002
Posts: 266
my first question was answered, thank you


What practices do you guys use for SVN that you feel are good practices? I intend to purchase pragmatic versioning on the 15th but reading a book and hearing actual stories are two vastly different experiences I've heard.
[ January 05, 2007: Message edited by: Matt Kidd ]
Frank Carver

Joined: Jan 07, 1999
Posts: 6920
While such a thing is theoretically possible, I don't really think it would be a good idea.

First: Allowing a pre-commit hook to "veto" a checkin is very dangerous.

What happens if you need to check something in in a hurry? or you need to check in a big lump of source code (perhaps produced by a third party)? Remember, the version control system is there to make sure you have something to go back to if/when you screw things. So the rule should always be to check in the source before making any changes, such as laboriously going through adding JavaDoc.

Second: Do you really want JavaDoc for every method, of every class?

I can understand that JavaDoc can be useful for methods which form part of a public API, but for internal and private methods the overhead of maintaining JavaDoc and needing to scroll past it to get to the "real code" seems too much.

Whenever I have worked on projects with mandatory JavaDoc, the great majority of JavaDoc comments ended up being useless defaults. Maybe your project has escaped this?

Third: There's the issue of deciding which changes to a method require a change to the JavaDoc.

I can imagine plenty of method changes which would not need a change to the JavaDoc. Any refactoring - by definition - changes only the internals of an operation without changing its interface.

What I have trouble imagining is a cost-effective way of putting enough intelligence in your pre-commit handler to determine if the JavaDoc is now out of step with the code. Anything smart enough to do that would probably be smart enough to write the JavaDoc in the first place


Read about me at ~ Raspberry Alpha Omega ~ Frank's Punchbarrel Blog
Matt Kidd
Ranch Hand

Joined: Jul 17, 2002
Posts: 266
you make a lot of good points. I'm going to run this by our senior developer.

The primary reason behind the hook was so that we would have documentation for our codebase. As it stands the knowledgebase behind the majority of the code that was written left several months before I joined the team. The hook an effort to a)force refactoring where needed b) get a grasp of our codebase and c) allow for new people to ramp up quicker.

I do see your point and that was one of the major hang ups I had with figuring out the hook. Sure I could write the hook, make it use grep, but then the major hurdle was the recognizing of the various method signatures AND then figuring out which methods changed and making sure those methods javadocs were updated.

It'd be easier to yell over to the next cube "hey...update your javadoc!!!" with a team this small. I think I should edit this to find out various repository best practices.
Frank Carver

Joined: Jan 07, 1999
Posts: 6920
Just as a helpful hint, it's not usually the done thing to delete or overwrite a question when you have an answer.

The main reason for this is that many search existing questions and answers for solutions to their problems, or even just like to read them to learn things. If you remove your question not only will people not be able to find it if they have a similar question, but if they do find my answer, they won't know what I was answering.

Removing the question also limits your (and other readers') ability to get alternative answers from other people with different skills and experience. Some of the most useful topics are the ones where an apparently simple question gets a variety of different answers.

The usual practice is to create a new topic if you have a new question. Don't worry, there's plenty of room here
Jeanne Boyarsky
author & internet detective

Joined: May 26, 2003
Posts: 32328

Based on my conjectures of the original question, it was something like "should I have a pre commit hook to force JavaDoc to be written"?

I agree with Frank that this would not be good because it limits commits excessively. A good place to enforce documentation (or other quality attributes) is in the build process. You can commit anything you want, but you can't build an artifact (jar, war, ear) out of it. And if you have a nightly build or continuous integration, you can enforce the rules every day.

[OCA 8 book] [Blog] [JavaRanch FAQ] [How To Ask Questions The Smart Way] [Book Promos]
Blogging on Certs: SCEA Part 1, Part 2 & 3, Core Spring 3, OCAJP, OCPJP beta, TOGAF part 1 and part 2
Ilja Preuss

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Matt Kidd:
my first question was answered, thank you

Do I understand you correctly that you therefore *replaced* the original question with a new one?

That makes this thread very confusing. Next time, please simply start a new thread instead.

The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
I agree. Here's the link:
subject: Your local Versioning best practices
It's not a secret anymore!