@return in phpDoc bij method chaining

Overzicht Reageren

Sponsored by: Vacatures door Monsterboard

Ward van der Put
Moderator

Ward van der Put

02/09/2013 13:45:14
Quote Anchor link
In een klasse gebruik ik method chaining, bijvoorbeeld:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<?php
class User
{
    private $Username;

    /**
     * @param string $username
     * @return ...
     */
    public function setUsername($username)
    {
        $this->Username = $username;
        return $this;
    }
}
?>


Wat hoort er in het commentaar achter @return?
Gewijzigd op 02/09/2013 13:45:37 door Ward van der Put
 
PHP hulp

PHP hulp

25/04/2024 13:10:54
 
Erwin H

Erwin H

02/09/2013 13:58:07
Quote Anchor link
De class, of bij voorkeur wat mij betreft de interface.
 
Kris Peeters

Kris Peeters

02/09/2013 14:01:25
Quote Anchor link
Het is niet de class, maar het object zelf dat teruggegeven wordt.

Ik vind iets als

@return $this, for method chaining

meer dan duidelijk genoeg.
Nu, misschien bestaat er een standaard antwoord voor deze vraag; dat weet ik niet.

Ik vind dat fout geformatteerd commentaar dat wel duidelijk is, beter is dan goed geformatteerd commentaar waar niemand iets aan heeft.
Gewijzigd op 02/09/2013 14:03:03 door Kris Peeters
 
Ward van der Put
Moderator

Ward van der Put

02/09/2013 14:32:35
Quote Anchor link
PHP maakt er zelf object(User) van. Om dit te reproduceren:

Code (php)
PHP script in nieuw venster Selecteer het PHP script
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
$u = new User();
$var = $u->setUsername('Handige Harry');
echo '<pre>';
var_dump($var);

class User
{
    private $Username;

    public function setUsername($username)
    {
        $this->Username = $username;
        return $this;
    }
}
?>

Wat zouden jullie dan het duidelijkst vinden?

• @return object
• @return $this
• @return object $this
• @return object User
• @return User
 
Erwin H

Erwin H

02/09/2013 14:54:54
Quote Anchor link
Gewoon het laatste.

Op zich vind ik de optie van Kris wel interessant. Ik betwijfel alleen of het zo nodig is. In situaties waarin een object een object van dezelfde class (of interface) teruggeeft gaat het 9 van de 10 keer om chaining. Zeker in geval van een setter. Daarnaast is het commentaar in het doc bij voorkeur de plek om verduidelijking aan te brengen mocht dat nodig zijn. Het blijft immers commentaar, niet een voorschrift.
 
Kris Peeters

Kris Peeters

02/09/2013 15:23:05
Quote Anchor link
Of eventueel zet je in het commentaar van de class zelf een algemeen commentaar, iets als

/**
* ... all setter methods return the User object, for method chaining
*/
Gewijzigd op 02/09/2013 15:23:28 door Kris Peeters
 
Wouter J

Wouter J

02/09/2013 16:30:25
Quote Anchor link
@return $this

Quote:
15.'$this', the element to which this type applies is the same exact instance as the current Class in the given context. As such this type is a stricter version of 'static' as, in addition, the returned instance must not only be of the same Class but also the same instance.

This type is often used as return value for methods implementing the Fluent Interface design pattern.


Bron: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#keyword
 
Ward van der Put
Moderator

Ward van der Put

02/09/2013 16:52:25
Quote Anchor link
Aha, ik wist niet dat er een PSR voor PHPDoc bestond.

Grappig om te zien dat we allemaal op ongeveer dezelfde lijn zitten. Dank allen!
 
Wouter J

Wouter J

02/09/2013 17:08:44
Quote Anchor link
Hij is ook nog proposed :)

Toevoeging op 02/09/2013 17:09:20:

Ik laat dit trouwens zelf altijd weg. Dat het $this returned is al heel duidelijk vanuit de code.
 
Ward van der Put
Moderator

Ward van der Put

02/09/2013 17:26:06
Quote Anchor link
Wouter J op 02/09/2013 17:08:44:
Ik laat dit trouwens zelf altijd weg. Dat het $this returned is al heel duidelijk vanuit de code.

Daarin heb je wel gelijk, maar meestal kun je het beter expliciet maken. Bij methoden zonder return gebruik ik bijvoorbeeld toch vaak een @return null om aan te geven dat de uitkomst “by design” zo is en er geen bedrijfsongeval heeft plaatsgevonden :)
 
Ozzie PHP

Ozzie PHP

02/09/2013 17:33:48
Quote Anchor link
Ward van der Put op 02/09/2013 17:26:06:
... en er geen bedrijfsongeval heeft plaatsgevonden :)

:)
 
Wouter J

Wouter J

02/09/2013 17:40:28
Quote Anchor link
>> Bij methoden zonder return gebruik ik bijvoorbeeld toch vaak een @return null om aan te geven dat de uitkomst “by design” zo is en er geen bedrijfsongeval heeft plaatsgevonden :)
Merk op dat je dan beter [c]@return void[/c] kunt gebruiken.

Ik schrijf altijd PHPdocs om dingen duidelijk te maken die niet duidelijk zijn. Bijv. "Sets the name" bij een User#setName method vind ik zinloos. En [c]@param array $options[/c] wanneer de signature [c](array @options)[/c] bevat vind ik ook nutteloos.
 



Overzicht Reageren

 
 

Om de gebruiksvriendelijkheid van onze website en diensten te optimaliseren maken wij gebruik van cookies. Deze cookies gebruiken wij voor functionaliteiten, analytische gegevens en marketing doeleinden. U vindt meer informatie in onze privacy statement.