javadoc interface + implementation + @overrides

[diggaa1984]

hiho,

hab mich grad mal was gefragt und will euch das nich vorenthalten
bsp folgt:

public interface SimplePerson {

    /**
     * Adds a new entry to the existing data.
     * 


     * @param attribute A new attribute.
     * @param value The value that will be assigned to the attribute
     * @return <code>true</code> if successfully added, else <code>false</code>
     */
    public boolean addEntry(String attribute, String value);
}

public class ArrayListPerson implements SimplePerson {

    /**
     * Given <code>attribute</code> must be different from existing attributes
     * and need to consist of at least 1 character.
     */
    public boolean addEntry(String attribute, String value) {
        if ((! attributes.contains(attribute)) && (!attribute.equals(""))) {
            attributes.add(attribute);
            data.add(value);
            return true;
        }//if
		
        return false;
    }//addEntry
}//class ArrayListPerson

so, wenn ich das ganze so gestalte, dann seh ich in der javadoc zu ArrayListPerson#addEntry nur den dortigen Comment .. soweit klar

Wenn ich statt dem Comment dort nur @Override davorschreibe, dann sehe ich in ArrayListPerson#addEntry den Comment aus'm Interface.

Nun die Frage, kann ich das mixen, also als Grundlage den Comment aus'm interface nutzen, aber zusätzlich den Comment der Implementierung erhalten?

also in der Javadoc sollte dann vielleicht sowas stehen:

Adds a new entry to the existing data.
Given attribute must be different from existing attributes and need to consist at least of 1 character.

Parameters:
attribute A new attribute.
value The value that will be assigned to the attribute
Returns:
true if successfully added, else false

 

[Ebenius]

Hallo,

an dieser Stelle möchte ich eben mal anmerken, dass @Override eigentlich nicht dafür gedacht ist, Methoden zu markieren die Methoden eines Interfaces implementieren. Mir ist mir hier im Forum mehrfach aufgefallen, dass dies von manchem anders gehandhabt wird.

Dazu sagt die API-Doc von @Override:

Indicates that a method declaration is intended to override a method declaration in a superclass. If a method is annotated with this annotation type but does not override a superclass method, compilers are required to generate an error message.

Gruß, Ebenius

 

[Verjigorm]

Hm ich hab gradmal nachgeschaut:
Eclipse setzt ein @Override vor die Methode...

 

[Ebenius]

Nun die Frage, kann ich das mixen, also als Grundlage den Comment aus'm interface nutzen, aber zusätzlich den Comment der Implementierung erhalten?

Was Du suchst ist {@inheritDoc}.

Diese Hinweise solltest Du ebenfalls lesen.

Hilft das soweit?

Grüße, Ebenius

 

[Ebenius]

Hm ich hab gradmal nachgeschaut: Eclipse setzt ein @Override vor die Methode...

:shock:

Meins nicht. Das ist eigenartig, ich kann dazu auch keine Einstellungen finden. Die Einstellung "Java » Code Style » Add '@Override' annotation for new overriding methods" ist eingeschaltet und funktioniert auch bei überschriebenen Methoden. Bei implementierten Methoden kommt da nix.

Wenn ich die '@Override' Annotation anhänge bekomme ich vom Eclipse JDT einen Compile Error "The method run() of type new Runnable(){} must override a superclass method" bei diesem Konstrukt:

new Runnable() {
    
  @Override
  public void run() {
  /* PENDING: Auto-generated method body */

  }
};

Meine Eclipse-Version:

Version: 3.4.0
Build id: I20080617-2000

Wie auch immer, die API-Doc sagt klar, nur überschriebene Methoden aus Super-Classes.

Grüße, Ebenius

 

[Verjigorm]

Ich benutze 3.3.1.1 mit denselben Einstellungen und da kommt ein @Override

Ich teste mal 3.4

 

[Ebenius]

Habe eben mal nach Referenzen im JDK-Source Code gesucht. Als Beispiel kann ich javax.swing.DefaultListCellRenderer aus JDK1.6.0_10 anführen. Einzige implementierte Methode "getListCellRendererComponent(...)" hat kein @Override, die ganzen überschriebenen "fireXXX(...)" haben die Annotation.

Grüße, Ebenius

 

[maki]

Wenn ich die '@Override' Annotation anhänge bekomme ich vom Eclipse JDT einen Compile Error "The method run() of type new Runnable(){} must override a superclass method" bei diesem Konstrukt:

Ab Java 6 ist das erlaubt.

Leider wurde die Doku nicht angepasst: http://blogs.sun.com/ahe/entry/override_snafu

 

[Ebenius]

Ab Java 6 ist das erlaubt.

Leider wurde die Doku nicht angepasst: http://blogs.sun.com/ahe/entry/override_snafu

Hmm, das war mir neu. Wenn ich Compiler Compliance Level auf 1.6 schalte, dann akzeptiert's der Compiler auch.

Danke für den Hinweis,
Grüße, Ebenius

 

[Verjigorm]

Nur so zum Abschluss nochmal:

3.4.1 schreibt bei mir auch @Override automatisch hin

 

[maki]

Nur so zum Abschluss nochmal:

3.4.1 schreibt bei mir auch @Override automatisch hin

Kommt auf den Compliance Level an

 

[diggaa1984]

ja son override is ja auch bei interfaces sinnvoll, wenn sich da mal die specs aendern, was wenn hoffentlich nur selten vorkommt, oder wenn man sich verschrieben hat beim methodenkopf, dann wirds eben dadurch gleich durch compiler gefischt, und man wird sofort auf den fehler aufmerksam.

und sonst funktionierts mit dem tag wunderbar, besten dank .. sollt ich wohl mal wieder öfter die javadoc-api wälzen .. wer weiss was es da noch alles tolles gibt ^^

 

[Ebenius]

Ab Java 6 ist das erlaubt.

Ist halt Mist, dass ich recht wenig mit Java 6 machen kann. Ich habe gerade erst durchkämpfen können, nicht mehr Java 1.4 kompatibel programmieren zu müssen. Java 6 ist beruflich sicher noch ein Jahr Zukunft für mich. :-S

Dass mich dann aber auch noch die Java 6 API-Doc belügt... :shock:

Tststs, Ebenius

 

[maki]

Das Problem kenn ich nur zu gut, bis vor einem 1,5 Jahren musste es Java 1.4 sein, danach 1.5.

Im Moment bin ich soz. frei, kann sich aber schnell wieder ändern...

Auf die Sache mit der @Override Anno bin ich nur gekommen, weil ich im letzten Projekt der einzige war, der den Compliance Level auf 1.6 hatte, bei mir gings, bei sonst keinem mehr... *peinlich*

Nachtrag: Glaube es ging mal darum, auch implementierte Methoden durch Annos prüfen zu lassen, anstatt nur überschriebene. Man hat sich dann gegen eine neue Anno (@Implements) entschieden, obwohl "to override" eigentlich ganz klar etwas anderes ist als "to implement".
Naja, die Jungs von Sun werden's schon wissen...

 

[diggaa1984]

warum bleibt man so ewig an alten versionen hängen, die lib mit auszuliefern is ja nu nich das problem, oder gehts darum, dass die sonstige Umgebung des Systems vielleicht nicht kompatibel mit neuen java-versionen wäre, oder weil nur teilsysteme erneuert werden, und der rest auf alter java-version beruht?

 

[maki]

warum bleibt man so ewig an alten versionen hängen, die lib mit auszuliefern is ja nu nich das problem, oder gehts darum, dass die sonstige Umgebung des Systems vielleicht nicht kompatibel mit neuen java-versionen wäre, oder weil nur teilsysteme erneuert werden, und der rest auf alter java-version beruht?

Es gibt keine Garantien dass die Software auf der neuen Plattform genauso funktioniert wie auf der alten, ein Softwaresystem zu testen kostet u.U. sehr viel Geld, ein Restrisiko gibt es immer, je weniger Tests, umso größer das Risiko.

Für die Fachabteilungen ist es eben kein Argument, dass die Entwickler dann mit der letzten Version arbeiten können.. speziell wenn dadurch erstmal keine neuen Funktionen hinzukommen.

 

[Ebenius]

warum bleibt man so ewig an alten versionen hängen, die lib mit auszuliefern is ja nu nich das problem, oder gehts darum, dass die sonstige Umgebung des Systems vielleicht nicht kompatibel mit neuen java-versionen wäre, oder weil nur teilsysteme erneuert werden, und der rest auf alter java-version beruht?

Bei uns hat's zwei Gründe:

1) Die Software die wir bauen wird im Intranet mehrerer Großfirmen eingesetzt und über JavaWS verteilt. Die RT kann ich dabei gar nicht ersetzen.

2) Es gibt Kunden die zuerst von allen Java-S/W-Anbietern schriftlich haben möchten, dass Ihr System gegen Java X getestet ist, bevor sie Java X zulassen und auf alle Ihre Clients gleichzeitig ausrollen.

So ist's leider manchmal. Ebenius