This week's book giveaway is in the OO, Patterns, UML and Refactoring forum. We're giving away four copies of Refactoring for Software Design Smells: Managing Technical Debt and have Girish Suryanarayana, Ganesh Samarthyam & Tushar Sharma on-line! See this thread for details.
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 ]
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
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.
Joined: Jan 07, 1999
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
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.
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