[Java] JavaDoc voor assert.

[Alarmnummer]

Ik gebruik nu het assert commando bij methoden/constructors en ik vraag me af hoe ik deze moet documenteren. Ik neem aan dat hier al wel een standaard voor is ontwikkeld. (Heb niets gevonden in de styleguide van sun).

[mbravenboer]

Aardig punt. Volgens mij is er (nog) niks specifieks.

Je zou misschien wel de @throws AssertionError kunnen gebruiken?

Op Javaworld las ik dit:

Unfortunately, Java's assertion facility does not mesh with the standard documentation system as closely as the exception facility. The Javadoc system includes information regarding all throws clauses declared by a method. Assertions do not draw such direct attention. This is certainly sensible for assertions in general, but rather unfortunate when using assertions to check the validity of input arguments to a public method.

en elders:

As far as I can see there is no link to Javadoc so there is no option to get assertions included in the documentation automatically.

Overigens raadt Sun hier:
http://java.sun.com/j2se/1.4/docs/guide/lang/assert.html
Het gebruik van assertions om pre-condities op parameters van public methoden te stellen af:

This convention is unaffected by the addition of the assert construct. An assert is inappropriate for such preconditions, as the enclosing method guarantees that it will enforce the argument checks, whether or not assertions are enabled. Further, the assert construct does not throw an exception of the specified type.

Omdat ze dit afraden, is het de vraag of ze het in de toekomst op zullen nemen in Javadoc. Ze raden het echter weer wel aan voor post-condities.

[tomato]

Vreemd, ziet Sun je dan liever exceptions of errors gebruiken voor pre condities? Dan zou ik toch neigen naar errors, het breken van conventies bij een interface is gewoon not done.

Voor welke situaties vindt Sun assertions dan eigenlijk gepast?

* tomato heeft het idee dat ie het een beetje kwijt is

Ons wordt met Java aangeleerd assertions te gebruiken (niet de Sun implementatie) voor pre condities...

[Alarmnummer]

er staat wel een artikel op javaworld:
http://www.javaworld.com/javaworld/jw-11-2001/jw-1109-assert.html
en hier nog meer info van sun:
http://java.sun.com/j2se/1.4/docs/guide/lang/assert.html

[mbravenboer]

tomato: Vreemd, ziet Sun je dan liever exceptions of errors gebruiken voor pre condities? Dan zou ik toch neigen naar errors, het breken van conventies bij een interface is gewoon not done.

Tja, het gaat vooral om conventies die je niet kunt uitdrukken in de interface (zoals beperkingen op integer range en dergelijke).

Er zit wel een reden achter waarom ze dit niet adviseren: assertions staan standaard uit. Als je je applicatie of library dus distribueert kan je er van uit gaan dat je assertions niet worden uitgevoerd. Men ziet assertions wellicht dus eigenlijk als een soort debugging functionaliteit... maar ja, daar hadden we JUnit al voor .

Ons wordt met Java aangeleerd assertions te gebruiken (niet de Sun implementatie) voor pre condities...

Welke implementatie dan wel? JUnit neem ik aan?

[tomato]

mbravenboer: Tja, het gaat vooral om conventies die je niet kunt uitdrukken in de interface (zoals beperkingen op integer range en dergelijke).

Precies, maar is het nou juist om daar assertions voor te gebruiken? Ik dacht eigenlijk altijd van wel, juist daar voor...

Welke implementatie dan wel? JUnit neem ik aan?

Ik kan me eigenlijk zo snel niet herinneren hoe het nu zat
Ik dacht dat we gebruik maakten van een Assert class:

code:

public interface Assert {

   static public void pre (boolean test, String message);

   static public void post (boolean test, String message);

   // en nog wat...

}

Zoiets was het dacht ik. Maar dit is toch geen standaard Sun klasse? Er zaten wat aparte klassen in een package bij het boek (die ik overigens nooit echt gebruikt heb), dacht altijd dat ie daar in zat...

[mbravenboer]

tomato: Precies, maar is het nou juist om daar assertions voor te gebruiken? Ik dacht eigenlijk altijd van wel, juist daar voor...

Idd, maar als assertions uit staan ben je flink de *piep* als je code serieus afhankelijk is van die condities. Vandaar dus dat ze het afraden...

Ik dacht dat we gebruik maakten van een Assert class

Ah, dat is wel iets anders ja... JUnit is meer voor test-cases. Daarbij kan je dan assertions gebruiken. Erg populair .

[Alarmnummer]

Op zondag 27 januari 2002 16:15 schreef mbravenboer het volgende:
Idd, maar als assertions uit staan ben je flink de *piep* als je code serieus afhankelijk is van die condities. Vandaar dus dat ze het afraden...

Je kan ervoor zorgen dat je class het alleen doet als assertions geenabled is.

[mbravenboer]

Alarmnummer: Je kan ervoor zorgen dat je class het alleen doet als assertions geenabled is.

Ik zag het ja, maar dat is nogal een paarde(n?)middel...

Ik heb trouwens ook geen idee of/hoe je aan kan geven dat je een executable jar wilt starten met assertions aan...

Lijkt mij een mooi moment om het Manifest naar XML formaat om te zetten .

[wasigh]

volgens mij heb ik iets gemist.. Wat is assert?

[Alarmnummer]

Op zondag 27 januari 2002 19:09 schreef wasigh het volgende:
volgens mij heb ik iets gemist.. Wat is assert?

er staat wel een artikel op javaworld:
http://www.javaworld.com/javaworld/jw-11-2001/jw-1109-assert.html
en hier nog meer info van sun:
http://java.sun.com/j2se/1.4/docs/guide/lang/assert.html

hier staat het keurig netjes in uitgelegd..


(het is ook vrij nieuwe.. sinds jdk1.4)

[tomato]

Alarmnummer: (het is ook vrij nieuwe.. sinds jdk1.4)

Vandaar dat er in het boek dat bij ons voor Java gebruikt wordt een eigen Assert klasse gebruikt wordt (boek is uit '99).

[Alarmnummer]

Ik gebruikt voorlopig deze constructie voor het assert statement. Ik maak hierbij dus onderscheid tussen pre en post conditions.

code:

    /**
     * Plaatst de 2e parameter van deze TwoParameterFunction
     *
     * @param parameter  de in te stellen 2e parameter.
     *
     * @exception RuntimeErrorException  wordt opgeworpen als er iets misgaat met het instellen.
     *
     * @precondition     parameter mag niet null zijn.
     *
     * @precondition     parameter2 kan niet ingesteld worden voor parameter1.
     *
     * @precondition     parameter2 kan niet voor de 2e keer worden ingesteld.
     *
     * @postcondition    het type van de function moet ingesteld zijn.
     */
    final public void setParameter2(ExprTreeItem parameter)throws RuntimeErrorException{
        assert parameter != null: "parameter can`t be null";
        assert parameter1 != null: "Can`t set parameter2 before setting parameter1";
        assert parameter2 == null: "parameter2 can`t be set again";
        
        checkParameter2(parameter2);
        assert getType()!=null: "type is not set";
        
        parameter2 = parameter;
    }

Als jullie nog op of aanmerkingen hebben hoor ik ze graag.

[Alarmnummer]

Ik zie dat ik al 1 fout heb gemaakt. Je mag alleen assertions gebruiken voor postcondities van niet publieke functies.

If, however, there is a precondition on a nonpublic method and the author of
a class believes the precondition to hold no matter what a client does with
the class, then an assertion is entirely appropriate.

[Alarmnummer]

Ik vind het trouwens super irritant dat ze dit niet wat gestandariseerd hebben . Ik hoop dat bij de final versie van jdk1.4 dit beter gedocumenteerd gaat worden anders krijg je een wildgroei. En dat willen we juist niet hebben

[mbravenboer]

Alarmnummer: Ik zie dat ik al 1 fout heb gemaakt. Je mag alleen assertions gebruiken voor postcondities van niet publieke functies.

Pre bedoel je denk ik.... daar had ik het juist de hele tijd over met tomato .

[Alarmnummer]

inderdaad, precondities