Cedric, > -----Original Message----- > From: [EMAIL PROTECTED] [mailto:eap-features- > [EMAIL PROTECTED]] On Behalf Of Cedric ROUVRAIS > Sent: 28 March 2002 23:14 > To: [EMAIL PROTECTED] > Subject: [Eap-features] [OT] JavaDoc or not? (was:Method contents popup > window) > > > hi, > > Writing a clean javadoc helps you formalize your thought and get your > ideas > straightend out, changing your source code shouldn't impact your javadoc, > unless it's a major change. > Your javadoc shouldn't be an exact copy of the source code ya know :o) > I've noticed that writing your javadoc improoves the quality of your code > because when you read your comments you sit back and say what am i doing > here? >
What you say is true. But what XP says is also true : it says that to formalize your thoughts and get your ideas straightened out, you should write unit tests first (before the implementation). You get exactly the same benefit as the one you get when you write the doc first. However you get several additional benefits : - you have some test code, - your code and tests are always in sync - you have some indirect documentation. Don't you think that the best documentation is often a simple example ? This is what unit tests are providing, a sample of how to use a piece of code. That said, I have not personally reached this level yet and although I write unit tests for almost all my code (in addition to javadoc), I am still not writing test first ... I'll really have to try it on a project soon ... ... maybe I'm too old (private joke :D). - Vincent > Your extreme version of XP is more of a lazy finger deviation of the > thought, IMO. > > a++ Cedric > > -----Original Message----- > From: [EMAIL PROTECTED] > [mailto:[EMAIL PROTECTED]]On Behalf Of Erik Hanson > Sent: jeudi 28 mars 2002 23:57 > To: [EMAIL PROTECTED] > Subject: [Eap-features] Method contents popup window > > > Trying to follow XP practices to the extreme, I've been trying to let the > code > of my methods be the documentation, so I haven't been creating JavaDoc > comments for my methods (except for public API methods). > > IDEA's very cool JavaDoc popup (ctrl-Q) feature therefore doesn't help me > as > much as it might help other people. It would be cool if IDEA provided a > method > contents popup (ctrl-alt-Q or something) that would show the contents of > selected method in the same kind of popup box. If the method was bigger > than > the box, the box could scroll or the contents could be truncated (maybe > truncation would force the programmer to make smaller methods). > > > (In case anyone is wondering, the argument against JavaDoc comments is > that > if > you don't change the comments when you change the code, you then have a > worse > situation (incorrect comments) than you'd have if you didn't provide any > comments. I haven't decided if I agree with it, but I thought I'd try it > out > for a while.) > > > _______________________________________________ > Eap-features mailing list > [EMAIL PROTECTED] > http://www.intellij.com/mailman/listinfo/eap-features > > > _______________________________________________ > Eap-features mailing list > [EMAIL PROTECTED] > http://www.intellij.com/mailman/listinfo/eap-features _______________________________________________ Eap-features mailing list [EMAIL PROTECTED] http://www.intellij.com/mailman/listinfo/eap-features
