[izpack-devel] Good practice for the Eclipse "Problem"-Tab...

[Markus Schlegel]

Coding convention is one thing.
Automatic Problem detection is an other thing...

Let me try to explain whats "wrong" with the automatic problem detection
of eclipse (at least for Javadoc comments):

When develpers have to "quieten" those problem-messages, they tend to
write things that are already clear and they tend to repeat things that
are already written elsewhere (and maybe just one line above!!) - just
to get rid of the message...

As an Example, you can look at almost every class in izpack that has
been altered because of this eclipse feature. Let me explain it with an
example taken at random from the trunk: "Compiler.java"


- Class comment is ok.
- Comments of the fields are also ok, even if the name of the fields are
selfexplainatory
- "setIzpackHome(String izHome)" nothing wrong with this, but it is
completely redundant to what the code (even in javadoc) says. Means: all
info that the javadoc comment gives, is already there in the method
declaration...
- The same applies for most of the methods in this class up to line 290
(there are 2 or 3 useful parameter descriptions and a handful useful
method descriptions)
--> the developer who wrote these comments had only one motivation:
quieten the eclipse problems... This just makes NO sense. Even if
Javadoc is a part of the Language.

What I wanted to say is, that if you will force writing Javadoc
comments, then do it by coding convention, but NOT by saying "checked in
code must not have any Javadoc-Warnings in Eclipse".

Don't get me wrong. I have also written such comments at some times, but
at least wen I came back through that code few years later, I thought
"what a stupid thing". 

So either you have to explain how a method does something or what a
method does and write just that, or let it be.

Of corse this is my opinion, and I am a newby in this project. But what
I saw up to now is, that there are some problems in the code which
should be soved, and that there is not plenty of time to do this. So why
waste time on writing unneeded and redundant things? And by the way: is
there any good reason why to develop with IzPack with only the Javadoc
when you have the source code available? 

Markus


-----Original Message-----
From: izpack-devel-bounces at lists.berlios.de
[mailto:izpack-devel-bounces at lists.berlios.de] On Behalf Of Marc
Eppelmann
Sent: Friday, December 01, 2006 8:24 PM
To: izpack-devel at lists.berlios.de
Subject: Re: [izpack-devel] Good practice for the Eclipse
"Problem"-Tab...

Hi,

+1 :-) Since we provide the Javadoc as HTML, these API Overview (or 
+better
Developer Reference Manual) should be also up to date and usable.

Marc

Am Freitag, 1. Dezember 2006 17:18 schrieb Bartz, Klaus:
> Hi Mrkus,
> I do not agree with you that it is a good practice to ignore eclipse 
> warnings. Yes, most of it are related to missing or corrupt java doc.
> May be we have not the time and/or not the knowledge to create 
> sufficient java doc comments for old code. But we can do it for our 
> new code. Also for getter and setter. It is possible to use template 
> for simple situation. You need a <ctrl> <shift> J grip... And you do 
> not forget the java doc at methods where it is really needed. It is 
> contents of the language and it is recommanded to comment all 
> non-private methods. Not all developer uses the source as docu. If we
do it not, the code will be not better.
>
> May be it is possible to use implicit developing rules if the 
> developing group consists of one or two people, but not with nearly 
> twenty. One makes no java comment, the other do not attend the dtd (or

> writes no) and some others do not write docu for the features or do
not update it at changes.
> Not forget different coding styles...
> To supress such chaos it is needed to say something about it from time

> to time (it is also addressed to me).
>
> Cheers
>
> Klaus
>
>
> -----Original Message-----
> From: izpack-devel-bounces at lists.berlios.de
> [mailto:izpack-devel-bounces at lists.berlios.de]On Behalf Of Markus 
> Schlegel
> Sent: Friday, December 01, 2006 9:49 AM
> To: izpack-devel at lists.berlios.de
> Subject: [izpack-devel] Good practice for the Eclipse "Problem"-Tab...
>
>
> Hi
>
> I read some posts about this the last few days and like to share a few

> thoughts about this.
>
> When I switched from JBuilder to Eclipse last summer with my project, 
> Eclipse showed up with several thousands Problems. First I thought, 
> "oh dear, there is so much wrong with my code? Lets fix all of this 
> and I get more reliable code (higher quality)...". When I got deeper 
> into this, I realized, that most of those problem warnings are 
> irrelevant. It just makes no sense to add a foll blown javadoc comment

> to a simple selfexplainatory method. What happens most in such cases 
> is, that the programmer then simply adds a dummy comment (no real 
> explaination, its there only to quiten eclipse). And in fact I saw 
> this in many projects. It just makes no sense to rewrite in javadoc
what is written in the method declaration already.
> Often it's also much better and sufficient to write a good class
comment.
> Then iot makes no sense to rewrite the comment for the methods again. 
> The other point that often happens with such (dummy) comments is, that

> - because they are irrelevant - they will not be maintained when 
> developing the code. What I like a lot more, are comments inside the 
> code block (as it is done in IzPack already very well I argue). But 
> this can not be tested with eclipse of corse...
>
> So maybe you should concentrate on real problems, open points and 
> fixing bugs rather than quitening eclipse's problem tab.
>
> Regards
>
> Markus
_______________________________________________
izpack-devel mailing list
izpack-devel at lists.berlios.de
https://lists.berlios.de/mailman/listinfo/izpack-devel