aspose file tools*
The moose likes Agile and Other Processes and the fly likes XP practise - Leaving out javadocs Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "XP practise - Leaving out javadocs" Watch "XP practise - Leaving out javadocs" New topic
Author

XP practise - Leaving out javadocs

Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
I'm currently reading O'Reilly's Java Extreme Programming Cookbook and recently came up with a paragraph where the authors suggested a practise that sounds a bit surprising to me, namely leaving out method comments for "self-documenting" methods.
I can see the authors' point--someone encountering a setX() method won't be baffled by missing javadocs and the javadoc (e.g. parameter name) might get out of synch with the code. However, I don't buy this practise for the following reasons:
1) Leaving out javadocs for the sake of more work for the coder is, IMO, unnecessary lazyness--not productivity. Even for set/get methods, javadocs are consistency if nothing else.
2) IDEs can make sure that parameters/exceptions are explained in the javadoc
What's your opinion?


Author of Test Driven (2007) and Effective Unit Testing (2013) [Blog] [HowToAskQuestionsOnJavaRanch]
Frank Carver
Sheriff

Joined: Jan 07, 1999
Posts: 6920
Consider the "default" javadoc for a method with no explicit javadoc comment.

generates:
Method Summary
 void setVolume(int volume)

I can't imagine what I could add to that to make it any more useful. Can you?
[ June 28, 2003: Message edited by: Frank Carver ]

Read about me at frankcarver.me ~ Raspberry Alpha Omega ~ Frank's Punchbarrel Blog
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5

Not trying to be a smart-ass but personally, I'd appreciate this javadoc when browsing the code, let alone browsing the HTML javadoc.
Actually, I wasn't aware that the latest javadoc generates any default javadoc. Can the default description be customized into something else than "Method Summary" somehow?
[ June 28, 2003: Message edited by: Lasse Koskela ]
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Ok, the following renaming would eliminate the need for the javadoc from a code-reading perspective. However, I think the javadoc browsing perspective still holds...
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Lasse Koskela:
1) Leaving out javadocs for the sake of more work for the coder is, IMO, unnecessary lazyness--not productivity.

I don't understand this argument. The point is that programmers should make their code as expressive as possible. Often (but not always), the need for a javadoc comment is a hint that the design of the code could be improved. I would always prefer a good design over good javadoc comments. (Of course this holds only true as long as every user of the code can access the source. For the documentation of external interfaces of libraries, javadoc still is very valuable.)
Even for set/get methods, javadocs are consistency if nothing else.

The question is what value such consistency would give you, and to what price...

2) IDEs can make sure that parameters/exceptions are explained in the javadoc

Naturally, IDEs can only repeat information that is already available in the source code. I wouldn't see any value in duplicating this info and having to maintain it.

What's your opinion?

I don't often document internal code anymore - not because I am lazy, but because I find that the time is better invested in making the code more expressive by itself.


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
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Lasse Koskela:
I think the javadoc browsing perspective still holds...

I wonder when you typically feel the need to browse in the javadoc. I typically prefer to browse the actual code and the accompanied tests.
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Originally posted by Ilja Preuss:
I don't understand this argument. The point is that programmers should make their code as expressive as possible. Often (but not always), the need for a javadoc comment is a hint that the design of the code could be improved. I would always prefer a good design over good javadoc comments. (Of course this holds only true as long as every user of the code can access the source. For the documentation of external interfaces of libraries, javadoc still is very valuable.)
...
I don't often document internal code anymore - not because I am lazy, but because I find that the time is better invested in making the code more expressive by itself.

This is a common opinion. However, I'm not convinced that "always read all source code" is better than "read the javadoc for functionality, and source if you're interested in implementation details". What I'm trying to say is that I think the service a method provides is better to be documented separately from how the service is implemented. Even if the code would be easy to understand, it's still more verbose than plain English.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Lasse Koskela:

Even if the code would be easy to understand, it's still more verbose than plain English.

Interesting - I most often find English to be much more verbose (and ambiguous - and most often even out of date) than code.
Can you please show us code that would benefit from a javadoc comment in your opinion? We could then explore wether there are possible refactorings and/or unit tests which make the code as well documented without the need for javadoc...
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
The important thing is that your organization should set a standard as to how C-style comments and singleline
comments are to be used, and then to follow that standard consistently.
As far as Javadoc comments isn't it easier to skim through Javadoc html so comments however brief can give some idea of the structure of the program - a big picture if you like.
I think standards need to be looked at from the maintainer's point of view (as many helpful comments needed - cut out the noisy comments) and the coder's ( write code that is as expressive as possible ).
As a maintainer if you find the comments are not reliable you won't be looking at them henceforth and you'd certainly appreciate expressive code.
Standards should strike a balance between the two.
By expressive code does one mean write three or four methods rather than a single all-encompassing method, or one liners that show a deeper understanding of the APIs that not everyone in your team will know at first glance ?
Well, it's up to the organisation to set the standards and who decides who is in the team.

Writing Robust Java Code
Elements of Java Style - Book Review -This tiny little paperback is modeled after its classic counterparts�Strunk & White's The Elements of Style (on English writing style) and Plauger's The Elements of Programming Style (on programming style).
regards
[ June 28, 2003: Message edited by: HS Thomas ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by HS Thomas:
The important thing is that your organization should set a standard as to how C-style comments and singleline comments are to be used, and then to follow that standard consistently.

What would such a standard look like?

As far as Javadoc comments isn't it easier to skim through Javadoc html so comments however brief can give some idea of the structure of the program - a big picture if you like.

Couldn't a good class browser do the same thing?
A high level class diagram - that could be valuable. But Javadoc...
I think standards need to be looked at from the maintainer's point of view (as many helpful comments needed - cut out the noisy comments)

I prefer to make my code so expressive that every comment becomes noisy...
Seriously: do you know a maintainer trusting documentation???
and the coder's (write code that is as expressive as possible ).

How do the views of coders and maintainers differ?
As a maintainer if you find the comments are not reliable you won't be looking at them henceforth and you'd certainly appreciate expressive code.
Standards should strike a balance between the two.

How would standards do that?
By expressive code does one mean write three or four methods rather than a single all-encompassing method

If that helps expressing intent of the code (and often it does), certainly. BTW, this also helps in some other aspects of development, like testability, extensability, reusability etc.
or one liners that show a deeper understanding of the APIs that not everyone in your team will know at first glance?

Perhaps. Unit tests could also help here.
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Ilja, your views are correct. However, I believe they're still too idealistic. You asked how many maintainers really trust the documentation -- I ask you how many developers really have it in them to write self-documenting code?
If they're able to write self-documenting code, are they really too ignorant to update the javadocs? Sure, sometimes even the best developer forgets to update the javadoc but if they're good enough to write good code, I think we could live with outdated javadocs from time to time.
I'm pedantic enough to try and I know a handful colleagues who do the same. Unfortunately, most of these guys are already waiting to get out of the project as they're too expensive for the client... Too bad I'm one of the few who know about an essential part of the system (whaddaya mean collective code ownership?) so I'll probably be one of those holding the cord when the project gets plugged...
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
whaddaya mean collective code ownership?)

Oh please, don't give up! I've only just started.
As in most things, the values of XP/Agile Development are sound. I think the level of the debate will need to be raised to scale upwards.
Let's face it systems will be bigger than ever before.
Perhaps a new set of values needs to be included.
Some suggest document first then test then code is a reasonable choice. Whether you do the documentation with the Unit Tests or with the code is open to debate. I suggest the code will outlive the Tests ( because code that's running perfectly OK for years is hardly likely to had the Tests touched in all those years) so it makes more sense to have the documentation with the code ( all those years hundreds of pair programmer eyes have been cast over the code) .
If your system isn't worth documenting it isn't worth running -- Nagler

[ June 28, 2003: Message edited by: HS Thomas ]
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
What would such a standard look like?

See Scott Ambler's writing Java code example.
While I'm not too happy with the C style example, I have also been guilty of them.
Actually not too happy with the Single line comments example - any business logic is subject to change so values are best held in data
The example would have been better as Apply discount to invoices subject to discount rule etc.

Comment Types:
1. Documentation
Use documentation comments
immediately before declarations of
interfaces, classes, member functions,
and fields to document them.
Documentation comments are processed
by javadoc, see below, to create external
documentation for a class.
e.g.
/**
Customer � A customer is any
person or organization that we
sell services and products to.
@author S.W. Ambler
*/

2. C style
Use C-style comments to document out
lines of code that are no longer
applicable, but that you want to keep just
in case your users change their minds, or
because you want to temporarily turn it
off while debugging.
e.g.
/*
This code was commented out
by J.T. Kirk on Dec 9, 1997
because it was replaced by the
preceding code. Delete it after two
years if it is still not applicable.
. . . (the source code )
*/
3.
Single line
Use single line comments internally
within member functions to document
business logic, sections of code, and
declarations of temporary variables.
e.g
// Apply a 5% discount to all invoices
// over $1000 as defined by the Sarek
// generosity campaign started in
// Feb. of 1995.

[ June 28, 2003: Message edited by: HS Thomas ]
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Couldn't a good class browser do the same thing?
A high level class diagram - that could be valuable. But Javadoc...

Yes , I agree they'd give more value. But what guarantee do you have that your current class diagramming tools would handle UML 2.x a few years down the line? I believe sequence diagramming has changed a lot since UML 1.x.
Javadoc and HTML with all their limitations are likely to be stable for a LONG while..
regards
[ June 28, 2003: Message edited by: HS Thomas ]
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Oh please, don't give up! I've only just started.

I won't give up. I'm just keeping a cease-fire until I'm moving on to another project where we're involved from the beginning and actually have a chance to affect things
As in most things, the values of XP/Agile Development are sound. I think the level of the debate will need to be raised to scale upwards.

Your point about escalating the discussions is to the point. Actually, we've been having lunch discussions for long and sometimes the project manager(s) (who are typically educated in economics, not technology) participate. They actually seem to agree and understand the benefits of many agile properties but when it's time to agree processes with the new client -- drum roll, please -- Iiiiit's waterfall and 4 months of up-front design!
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Iiiiit's waterfall and 4 months of up-front design!

I'd say Agile Designers are lacking in your environment.
Probably a chance for you to step in and show them how. Sometimes waiting for the NOD ain't the answer or changing projects . On a new project you may find you have to cover the same ground all over again. In your situation I'd try and get a job on the Modelling front and even if it's waterfall if you have shown to deliver more rapidly agilely that's more time for lunch breaks to raise the level of debate .
Nobody is going to knock you for delivering a good product in less time.
Ever heard of the JF*DI approach ? The Sun Tzu Art of War comes to mind too....
Good Luck!
regards
[ June 28, 2003: Message edited by: HS Thomas ]
Frank Carver
Sheriff

Joined: Jan 07, 1999
Posts: 6920
Actually, I wasn't aware that the latest javadoc generates any default javadoc.
Javadoc has always generated an entry for every public method, showing the method name, return type and parameter names and types. If you name your methods and parameters reasonably well, you don't need anyting else.
Try running javadoc on some uncommented classes and see what you get. Then think if changing the method name or parameter names would make it more useful.
Taking the code example from above:

I might simply change it to something like

The bit about 0..100 was always redundant. Afterall, that's part of the definition of a percentage. If it only allowed a range of 53..85%, then that might merit commenting.
After this change, the above javadoc comment is now redundant, and should be removed just like any other duplication.
Can the default description be customized into something else than "Method Summary" somehow?
Why would you want to? You still get the "method summary" for commented methods. Try it and you'll see what I mean. It was impossible to paste in the actual generated HTML.
For me, the bottom line is: If a javadoc comment adds no new information to that already communicated by the method and parameter names, you should not create one. Duplication is bad, wherever and however it occurs.
[ June 28, 2003: Message edited by: Frank Carver ]
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Originally posted by HS Thomas:
I'd say Agile Designers are lacking in your environment.

We do have good designers. Hell, I've met a couple of the smartest guys ever in this project (not just techie-smart but process/method, management, business). It's just that the big decisions were made lightyears ago and we don't get the budget to change these things at this point (and I don't really think it would be beneficial in a ROI sense). On the smaller scale, we don't do up-front but stand-up design discussions and sketches during the (sub)project.
Originally posted by HS Thomas:
Ever heard of the JF*DI approach ? The Sun Tzu Art of War comes to mind too....

JF*DI is exactly what we're doing... We'd never get an official approval for pair programming (even for parts of the system) but when we call it "asking for assistance" everybody's happy. Actually, the morale of JF*DI was discussed here about a month ago on some XP-adoption related thread.
Btw, as which form would you say Sun Tzu would've classified my project?
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Originally posted by Frank Carver:
Duplication is bad, wherever and however it occurs.

True. I'll rest my case. Maybe I just need to rethink my conception of "consistency" (perhaps Beck & Co didn't mean it to cover also the javadocs...).
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Hi all,
Here's a transcript from a Scott Ambler chat in China.
alou对大家说: I think most of us may think that AM is suitable 'cause we are lazy(2002/03/11 11:53)
scottambler对fly_sky说: I think that XP is real and it's here to stay. It will evolve over time(2002/03/11 11:53)
scottambler对alou说: Many people believe that the best developers are the lazy ones. ;-)(2002/03/11 11:53)
scottambler对alou说: You should use AM only if that's the best option for you, not because you want an excuse not to write documentation.(2002/03/11 11:54)
scottambler对alou说: In fact, the AM book and the AM site talks a fair bit about documentation and how to be effective creating it.(2002/03/11 11:54)
simaetin对scottambler说: From the martin folwer, the essence of the agile method is adaptive and people-intensive which are quite different with the old process.(2002/03/11 11:54)
Charity_Zhou进入聊天室.(2002/03/11 11:54)
Charity_Zhou对scottambler说: thanks , bye(2002/03/11 11:54)
scottambler对alou说: Many developers may find that AM asks them to do more modeling than what they did in the past.(2002/03/11 11:55)

UMLChina
He reflects on Sun Tzu - ancient philosophy and new practices.
Lasse, I couldn't tell what form your project is in unless it's from a viewpoint of your beating a hasty retreat.
He shares other insights too.
If you were lucky enough to work on an XP project than you'd probably have done more modelling than if you were not.
New projects at inception are likely to start small and need XP.
But once the requirements stop changing that much it's time to settle and go RUP or EUP(Enterprise UP).
But he also says software development is getting lighter..
scottambler对simaetin说: I think that software development will become more agile over time, but it will take a generation to do so.(2002/03/11 11:47)

so you could choose NOT to go RUP/EUP.
Illja and Frank must be some of the best developers . Perhaps you should adopt their stance,Lasse. I'll have to review my comments on documentation.
Software development shouldn't be about bean counting (pardon the pun) e.g Lines Of Code(not counting lines of documentation LODs) .
I may refuse to document again. Big systems can be broken down into and managed as smaller systems.
But then Scott W Ambler says pedantically :
scottambler对simaetin说: Heavy methods will never go away, they work very well in some situations. In fact, I've done work on something called the Enterprise Unified Process (EUP) -- visit www.ronin-intl.com -- for details.(2002/03/11 11:52)
)
scottambler对simaetin说: That's a fairly heavy method as it extends RUP to include a new phase and two new disciplines/workflows.(2002/03/11 11:52)

Adopting the Enterprise Unified Process (EUP)
regards
[ June 29, 2003: Message edited by: HS Thomas ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by HS Thomas:
But once the requirements stop changing that much it's time to settle and go RUP

Well, allowing requirements to change is only one of the benefits of XP. Others are:
- Giving early return of investment. XP teams have a working, releasable system (containing the most important features) from week one. If the customer needs to demo the system, for example, he simply gets the yesterdays afternoon build on CD. If the project needs to be canceled, he gets a system worth the currently invested money (instead of a shelf of documents).
- Giving much data to manage the project. Every two weeks, the customer gets new data on how much of the system is done (actually working, as shown by the acceptance tests) and how much the team expects to get done till delivery date (based on the data accumulated in the past). Given that data, he can react early.
- Allowing the developers to learn - and to put new knowledge into the system immediately. Even with unchanging requirements, the design can only be ultimately validated by putting it into code. Test-first, refactoring etc. are still likely to help here.
So, even with requirements cast in stone (which I am not convinced really exist for any project), I would still prefer to work XP-style.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Frank Carver:

The bit about 0..100 was always redundant. Afterall, that's part of the definition of a percentage. If it only allowed a range of 53..85%, then that might merit commenting.


But wait - where do the constraints come from? Do they also occur elsewhere? Possibly there is an abstraction awaiting to be manifested in its own class?
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by HS Thomas:
Yes , I agree they'd give more value. But what guarantee do you have that your current class diagramming tools would handle UML 2.x a few years down the line? I believe sequence diagramming has changed a lot since UML 1.x.

Why would I care?
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Illja, I was almost 100% convinced by your argument but now I ask myself why did SW feel the need for yet another process methodology i.e. EUP. True he has only extended RUP, but even then ....
Do you think you cannot work XP-style within EUP / RUP ? Would that remove the benefits you mention above ?
regards
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Why would I care?

Ummm, The diagram may be open to newer intepretation with newer UML standards , and therefore newer diagramming tools?
In the transcript given above ( I think) , Scott Ambler says he will be writing a new version of his book The Object Primer with the release of UML 2.0 and he'll be including Agile Modelling. UML 2.0 is still a while from release so I think that's significant.
I ask this with all respect of your vast OO experience as I can see from your posts here and on the UML forum.
Ummm, The diagram may be open to newer intepretation with newer UML standards ,and therefore newer diagramming tools?

Oh , I guess you'd treat that as another event generating a change requirement and just re-factor them in , huh ?
mega

regards
[ June 29, 2003: Message edited by: HS Thomas ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by HS Thomas:
/**
Customer � A customer is any
person or organization that we
sell services and products to.
@author S.W. Ambler
*/

I would be scared if the developers needed such a comment - they somehow had to be rather disconnected from the project if they didn't knew it by heart.
I could imagine something like this being stated in the high level system metaphor, though.
/*
This code was commented out
by J.T. Kirk on Dec 9, 1997
because it was replaced by the
preceding code. Delete it after two
years if it is still not applicable.
. . . (the source code )
*/

I would just delete it *know* - the version management system will provide the information on when and by whom it got deleted, and the option to restore it.

// Apply a 5% discount to all invoices
// over $1000 as defined by the Sarek
// generosity campaign started in
// Feb. of 1995. [/i]

public void applySarekGenerosityCampaign() {
applyDiscount(new Percentage(5), new GreaterThanConstraint(new Dollar(1000)));
}
Just as an example, of course - actual code would heavily depend on surrounding infrastructure and used system metaphor.
There would also be documentation in the form of executable acceptance tests.
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
All points agreed.
So everything in the Writing Java code example was unnecessary.
I think the trap some (me) fall into is forgetting that developers are involved in modelling and other artifacts of the communication between them and the customers.
So Class Diagrams and tests(Unit and Acceptance) and self-expressive code form the documentation and that is sufficient.
In maintenance , the same documentation are available and maintained at the same time.
Thanks.That's opened my eyes a bit.
Most documentation is usually signifying a lacking in the Modelling analyses ,testing or coding.

regards
[ June 29, 2003: Message edited by: HS Thomas ]
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
The above points listed by Illja are enforced by this article.Documentation Happens
(by Scott Ambler again).It's unnecessary, it happens unless stakeholders can be convinced otherwise to trust their developers to do what is required i.e they have the best developer team
they can possibly get.
regards
[ June 30, 2003: Message edited by: HS Thomas ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
http://www.xprogramming.com/xpmag/natural.htm is also a good article on the subject.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by HS Thomas:
I was almost 100% convinced by your argument but now I ask myself why did SW feel the need for yet another process methodology i.e. EUP.

From http://www.enterpriseunifiedprocess.info/ it seems as if what EUP adds to RUP are basically non-development roles and activities (like operating the system in the production environment, supporting end-users and retiring the system once it isn't in use anymore).
Do you think you cannot work XP-style within EUP / RUP? Would that remove the benefits you mention above?

You certainly can work XP-style and claim that you are doing RUP - after all, Rational is even providing an XP plugin for its RUP software.
The EUP extensions probably could also be applied in an agile way, though the papers *do* have a much more heavy weight feeling to me as presented.
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
Yes, the Enterprise Management Discipline covers long-term strategic objectives. Something a senior Business analyst should be well aware of, or try to be aware of..
Lasse, if you are still there I'd say these XP guys are fighting the Sun Tzu War. They look after the XP stuff pretty good. I take back that comment about you being in hasty retreat.
It now seems your project has retreated onto familiar ground (Waterfall methodology , did you say).
A place you wouldn't want to go to. It's difficult imagining how you'd work XP-style within Waterfall Methodology.
Though, there is such a thing as planned releases - find the high ROI - high risk features first and tackle those then go on to the next set of ROI-high risk features. That could be done Agilely.
So even if the stakeholders think it's Waterfall
it's actually XP.
What do you think, Illja . If XP is an instance of RUP, can't RUP be an instance of Waterfall ?
Time to start a new thread which I'll start here
Can't RUP be an instance of Waterfall

regards
[ June 30, 2003: Message edited by: HS Thomas ]
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I'll jump back to the original topic - javadoc.
If code needs a comment to explain it, there is something wrong with the code!
Reading code with this in mind and refactoring to remove the need for comments leads to better names, smaller methods. Many of which also happen to be more testable.
There are exceptions. I'll sometimes explain paths NOT taken. "Tried the obvious foo.bar() here and it blew up because ..." I sometimes note changes, especially when they tie back to bug fixes service requests from customers.
Where I like to put JavaDoc is on the PACKAGE. Describe the most stable parts - the executable main() or interfaces that people are likely to use from outside the package. Why they might use them, how to decide between alternatives. If there are no stable bits, maybe describe why and how to do maintenance.


A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Lasse Koskela
author
Sheriff

Joined: Jan 23, 2002
Posts: 11962
    
    5
Originally posted by HS Thomas:
...It now seems your project has retreated onto familiar ground (Waterfall methodology , did you say).
A place you wouldn't want to go to. It's difficult imagining how you'd work XP-style within Waterfall Methodology.

Yep, waterfall is the closest for the current process (it actually has another name given by the client but it's nothing more than a well-defined waterfall).
It's not that difficult to work XP-style on the root-level. For example, a 40-hour task can be XP'd quite well by one person. It doesn't cover any team-related practises but is still better than spending the first 16 hours drawing Rose models.
Originally posted by HS Thomas:
Though, there is such a thing as planned releases - find the high ROI - high risk features first and tackle those then go on to the next set of ROI-high risk features. That could be done Agilely.

We have planned releases and take the high importance stuff in first. We are building the software incrementally but not iteratively. Meaning that the increments are there but the increments are built in one big piece.
Thanks for the virtual support guys
HS Thomas
Ranch Hand

Joined: May 15, 2002
Posts: 3404
We have planned releases and take the high importance stuff in first. We are building the software incrementally but not iteratively. Meaning that the increments are there but the increments are built in one big piece.

As long as you are One Happy chappy. It seems to me your stakeholders are missing out.
They have on board a team of willing and able XPers and still insist on going Waterfall.(Wafflers as opposed to XPers, RUPers).
It doesn't cover any team-related practises but is still better than spending the first 16 hours drawing Rose models.

I still get this gut-feeling your project's modellers weren't modelling Agilely - weren't that close to the Customers for whatever reason.
I'm used to the above scenario but I've always accepted that that's the way things were done.
I think it's tied to their need to have ALL requirements in hand first, to be seen to be managing them.
Begs the Question - Would the same approach be taken ,say , to Life Management ?
regards
[ July 01, 2003: Message edited by: HS Thomas ]
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Stan James:
There are exceptions. I'll sometimes explain paths NOT taken. "Tried the obvious foo.bar() here and it blew up because ..." I sometimes note changes, especially when they tie back to bug fixes service requests from customers.

Of course. I also have some comments like "workaround for bug in [some thirdparty library, version x] - try to remove for later versions".
The practice isn't "never write a code comment". It's "don't write a code comment if it can be made unnecessary by better code".
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
I just found another place I had added a comment: overriding an empty method in an abstract class. The method name and argument name were so generic that they gave no clue what I wanted to accomplish so I had to do it the comment way.
I surely overstated the case for not commenting, but was just too rushed to add much subtlety. I really try to make the code express itself that well. It's a good thing to strive for!
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Originally posted by Stan James:
I just found another place I had added a comment: overriding an empty method in an abstract class. The method name and argument name were so generic that they gave no clue what I wanted to accomplish so I had to do it the comment way.

What did the comment look like? Could you have had the method just delegating to a method with a more expressive name?
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
Sure could have. I'll go back and see how that looks.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: XP practise - Leaving out javadocs