"Il y a peu de choses qui me soient impossibles..."
"Leadership is nature's way of removing morons from the productive flow" - Dogbert
Articles by Winston can be found here
Out on HF and heard nobody, but didn't call CQ? Nobody heard you either. 73 de N7GH
"Il y a peu de choses qui me soient impossibles..."
Les Morgan wrote:...
Stephan van Hulst wrote:Again, I think you've answered your own question. If you're repeating in comments what's in (private) code, then why write the comments at all? The point of using the private methods is to make the code more legible. If the comments make the code less readable, then leave them out. I rarely document my private methods because most of them are very short and have descriptive names. At most, I document exotic parameters and what exceptions are thrown. It seems pointless to write comments because of the dogmatic "all members must be documented".
Members used outside of the class should be well documented though, because those are the parts that have to be unit tested.
Stephan van Hulst wrote:Well, for anything that's not private, you should at least use the @throws and @return tags, if applicable. If the methods are mutators that are more than simple setters, you should also document the post-conditions. This is important for unit-testing all applications, not just APIs.
Remember that your class outline automatically becomes somewhat of an API if you use public and protected access, because even if you don't publish your code, they may still end up in modules that are reused by your company.
Avor Nadal wrote:Let's suppose that I had this:...
"Leadership is nature's way of removing morons from the productive flow" - Dogbert
Articles by Winston can be found here
Stephan van Hulst wrote:What do you mean, the same paragraph in different places?
Avor Nadal wrote:But I could go further and make this need extensible to several classes. For example, I've many EJBs which may throw the same type of exception, because of the same reason. This means that the descriptions of their @throw tags are exactly the same. If I want to do a small change, I've to run a search & replace to update all the matches, which is a risky and slow process.
I'm thinking about an identifier that could be embedded in certain JavaDoc tags, so that it's easy for the IDE to detect which paragraphs are supposed to be the same, regardless of their location. This would allow a kind of re-factoring at the JavaDoc level.
"Leadership is nature's way of removing morons from the productive flow" - Dogbert
Articles by Winston can be found here
Winston Gutkowski wrote:
I should add that it's by no means the only solution, but it seems to fit this particular example.
Avor Nadal wrote:Really I just wanted to put a case in which you need some auxiliary variables to prepare the object that you're interested on. This happens very often and, in some case,s it's tiring to create a method just to encapsulate 2 or 3 lines.
"Leadership is nature's way of removing morons from the productive flow" - Dogbert
Articles by Winston can be found here
However, might it not be possible to put this information in your Exception class? Or - possibly even better - in the constructor method that you generally use?
Then your @throws tag could simply be something like:
* @throws MyEJBException as described {@link MyEJBException#MyEJBException(String, int, double) here}.
And BTW, you do realise that your example could be shortened by simply re-ordering it, viz: