[CCA Standards] PHPdoc @return void

[Tristan Lins]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Moin zusammen,

ich habe gerade eine Extension von mir an PSR1+2 und den Code Style den
wir von der CCA bereitstellen angepasst. Eine Sache war mir dabei wieder
aufgefallen: @return void

Es gibt durchaus einige Gegenstimmen, bspw. hier:
http://code.garyjones.co.uk/why-return-void-is-wrong

Ich will die ganze Diskussion nicht noch mal durchkochen. Ich will aber
2 Argumente nennen, warum ich der Meinung bin, dass "@return void"
durchaus sinnvoll ist.

1. Vollständigkeit und Konsistenz

Es kommt nicht selten vor, dass phpdoc vergessen wird oder unvollständig
ist. Das fehlen von @return kommt ähnlich häufig vor, wie das fehlen von
einzelnen @param Deklarationen. Deshalb kann ich eigentlich niemals
sicher sein was es bedeutet.

> @return fehlt, heißt das jetzt die Methode hat keinen Rückgabewert 
> oder hat der Entwickler einfach vergessen es zu definieren?

Natürlich können IDEs durch die Inspection hier weiter helfen. Aber
zum einen muss man die Inspection nicht bemühen, wenn man genau
definieren kann dass es keinen Rückgabewert gibt und zum anderen wären
wir in Punkto IDE beim 2. Punkt:

2. Fehlerresistenz

Das möchte ich mit 2 kurzen Beispielen verdeutlichen:

**Beispiel 1**

> interface MyInterface { /** @return void */ public function
> func(); }
> 
> class MyClass implements MyInterface { public function func() { 
> return true; } }

Im Beispiel 1 wird das "return true;" einen Fehler werfen (bei einer
vernünftigen IDE). Und auch mit einem UnitTest lässt sich das relativ
genau analysieren und testen.

**Beispiel 2**

> interface MyInterface { public function func(); }
> 
> class MyClass implements MyInterface { public function func() { 
> return true; } }

Im Beispiel 2 jedoch wird keine IDE den Fehler finden. Das fehlen von
@return bedeutet nämlich nicht automatisch, dass es keinen Rückgabewert
gibt, sondern dass der Rückgabewert nicht definiert wurde. Davon gehen
zumindest die meisten IDEs aus.
Man könnte das ganze mit einem UnitTest versuchen gerade zu biegen,
aber im Endeffekt sagt einem der UnitTest dann auch nur "hey, da
stimmt was nicht schau mal nach", anstatt dass er genau sagen kann
"hey, du darfst da keinen Wert zurück geben".


Eure Meinungen würden mich interessieren.
MfG Tristan

- -- 
Tristan Lins - Inhaber, Softwareentwickler
bit3 UG (haftungsbeschränkt)
Bismarckstr. 45 · 56470 Bad Marienberg
info at bit3.de · http://bit3.de · 0261-45093253
Amtsgericht Koblenz, HRB 23386
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJUawOyAAoJEP7dYl7CqfrdSUIH/07MeY5fT/Fg4IGJkUUmwdFO
s+lc2/YnPAE/06bld8ftoCZNNg4CejO9C2ajIn3oNNvcjj7J+hXQktzTiR2WQPFy
XjhgLmfYs/AlfGLfT77yDCbaFSDrZ0gjPm3iGDqJe2s20FSqs45HMC/CL6xjbu8X
8zAmnPKtyoi9hV7lUmG6fSZrgW7qQUnKhGdZYgAoS+4V59O6wZbY6Znfju7N4AgH
rVsHLWCW6SQlAlB055npIZNzKa1VTJJKrCI3dQCC45Qyz0ozQZKcWDq6Db1nAtm+
EzQahdOocwMLaOOxGDR+wAZ0fdufgL44OZUUHmBHKATJE/b5gHSwLkiabmhO8rY=
=pPQf
-----END PGP SIGNATURE-----