APF Coding Standard

Hierein gehört alles, was in den übrigen Foren keinen Platz findet. // Please post here in case your topic doesn't fit enywhere else.
dingsda
Beiträge: 49
Registriert: 03.02.2014, 04:00:36

Re: APF Coding Standard

Beitrag von dingsda » 25.05.2014, 17:00:55

ich glaub doxygen und phpdoc brauchten die angabe im docblock nur früher als die sichtbarkeit in php noch nicht richtig unterstützt wurde.
es gibt auch jetzt schon einige stellen, wo kein tag für die sichtbarkeit im docBlock zu finden sind und doxygen trotzdem die richtige sichtbarkeit anzeigt. hab es auch mit kleineren code änderungen mal ausprobiert, ob es funktioniert (allerdings weiß ich auch nicht ganz ob ich doxygen richtig benutze. meine ergebnisse sehen eher bescheiden aus teilweise)
selbiges gilt für static und abstract.

falls doxygen die angabe im docblock wirklich nicht braucht könnte man die tags wirklich entfernen. entweder in einem rutsch mit der IDE und der find & replace funktion oder einfach nur schritt für schritt immer in den dateien wo aktuell sowieso änderungen gemacht wurden.

Benutzeravatar
dr.e.
Administrator
Beiträge: 4555
Registriert: 04.11.2007, 16:13:53

Re: APF Coding Standard

Beitrag von dr.e. » 29.05.2014, 16:56:35

Das klingt gut. Magst du ein Issue für 2.2 eröffnen? Ich würde das dann gerne im Rahmen der 2.2-er Entwicklung tun wollen.
Viele Grüße,
Christian

dingsda
Beiträge: 49
Registriert: 03.02.2014, 04:00:36

Re: APF Coding Standard

Beitrag von dingsda » 29.06.2014, 12:39:27

Ich hab zwar schon zwei issues dazu im bugtracker eröffnet aber schreibt trotzdem hierrein, weil es ja auch die codingstandards betrifft und ich hier besser code schreiben kann.

wie bereits angekündigt hab ich weitere tests gemacht und dabei folgende dinge festgestellt:

unnötige doctags

folgende tags braucht doxygen nicht:
@private
@protected
@public
@static
@abstract
@package
@interface
@class

phpStorm und netbeans benötigen sie ebenfalls nicht.

docblock richtig schreiben

bei phpStorm machen dies oben genannten tags sogar probleme. phpstorm erkennt keine beschreibung für methoden/klassen/membervariablen, wenn vor der beschreibung irgendein ein doctag ist
korrekt müssen daher die docblocks so ungefähr aussehen

Code: Alles auswählen

/**
* klassenbeschreibung als erstes
* 
* @author oder andere tags
*/
class bar{
   /**
   * methodenbeschreibung auch immer als erstes
   *
   * @param type $param [beschreibung für paramater, bei type bitte immer auch tatsächlich einen
   *                                 gültigen typ angeben]
   * @weitere tags
   */
   public function foo($param){

   }
}
 
habe oft in den docblocks @const gefunden. kennt weder phpDoc nicht, noch doxygen oder eine IDE.

bei konstanten erkennt phpstorm eigenständig den typ. es ist daher nur eine beschreibung über der konstante nötig

Code: Alles auswählen

/**
 * diese konstanten bewirkt bla blub
 */
 const MY_CONST = 1;
 
für netbeans und doxygen muss der tag @var eingefügt werden um den datentyp für eine constante anzugeben. zur richtigen nutzung bzw problemen von @var gleich mehr

doxygen erkennt keine beschreibungen von konstanten, oder properties von klassen, wenn sie nach einem tag kommen, für netbeans gilt das selbe.
für netbeans muss ein docblock für eine property z.b. so aussehen

Code: Alles auswählen

/**
 * diese beschreibung wird angezeigt
 *
 * @var int (alles was hier noch kommt wird nicht angezeigt bei der code completition)
 */
 protected $foo = 1;
 

für doxygen muss der docblock so aussehen:

Code: Alles auswählen

/**
 * diese beschreibung wird in der doxy-docu angezeigt zusammen mit dem datentyp für die property
 *
 * @var int $foo
 */
 protected $foo = 1;
 
nutzt man nur "@var int" oder irgendeine andere form (z.b. @var vor der beschreibung), dann wird nur die property in der docu angezeigt ohne beschreibung oder datentyp.

im internet findet man mögliche lösungen für doxygen. z.b. einen input filter bei doxygen registrieren, der den docblock umschreibt. könnte man natürlich auch gleich als konvention einführen, dass das so geschrieben werden soll, auch wenn für ides die nennung der variablen unnötig ist.

hab auch andere unbekannte phpdoctags gesehen. z.b. @desc beim apfelsms. kenne nicht alle IDEs, daher die frage: gibt es welche wo es nötig ist die beschreibung so anzugeben? imho wird die einfach als erstes in den docblock geschrieben.

thema @inheritdoc / docblock leer lassen

zum thema inheritance musste ich leider feststellen, das netbeans da ziemlich schlecht funktioniert. es erkennt leider nicht das phpdoc von einer vaterklass oder interfaces, wenn die methode überschrieben wird. egal ob der docblock leer gelassen wird oder @inheritdoc drin steht. nur wenn die methode gar nicht überschrieben wird wird der docblock von der elternklasse angezeigt, was natürlich bei interfaces und abstrakten klassen nicht möglich ist.

phpstorm und doxygen dagenen erkennen die geerbte docu problemlos, egal ob @inheritdoc drin steht oder nicht.

Tests mit anderen IDEs / Rückmeldungen
außer phpstorm und netbeans habe ich nur noch in aptana ein bischen getestet. da es bei mir immer glückssache ist, ob aptana überhaupt richtige code completition macht (bei größeren projekten funktioniert es einfach mal gar nicht) habe ich es dann wieder gelassen. weiß jetzt auch nicht mehr, was nun funktioniert hat und was nicht.

weitere tests bei anderen IDEs währen wünschenswert. vor allem eclipse ist glaube ich noch recht beliebt. (nutzt das jemand?)

nutzt hier jemand wirklich viel netbeans und kann meine beobachtung bezüglich des erbens der doku mehr sagen?
beim querlesen im inet klang es teilweise so, als würde soetwas eigentlich doch unterstützt werden.
soll dennoch @inheritdoc eingeführt werden? wenn tests von anderen IDEs zeigen, dass es dort funktioniert könnte man es finde ich machen. andere frameworks haben das auch eingeführt (z.b. Symfony).

Ich mach heute abend wahrscheinlich ein pull-request mit meinem codeänderungen. bin grad in der uni und das uninetz blockiert die verbindung zu github

Benutzeravatar
dr.e.
Administrator
Beiträge: 4555
Registriert: 04.11.2007, 16:13:53

Re: APF Coding Standard

Beitrag von dr.e. » 29.06.2014, 13:55:07

Hi,

danke für deine Recherche! Gefällt mir sehr gut! :)

Magst du vielleicht den Post unter http://wiki.adventure-php-framework.org ... g_Standard einfügen? Dann haben wir eine konsistente Dokumentation.

Was den Pull-Request angeht, macht es vielleicht Sinn, wenn du die inzwischen vollzogenen Änderungen zunächst merged, es ist doch einiges zusammen gekommen... ;)
Viele Grüße,
Christian

dingsda
Beiträge: 49
Registriert: 03.02.2014, 04:00:36

Re: APF Coding Standard

Beitrag von dingsda » 29.06.2014, 19:42:12

Das mit dem mergen muss ich mir nochmal genauer anschauen. bisher hatte ich nie mit konflikten beim mergen zu tun :mrgreen: . und heute keine zeit mehr für. pull-request kommt dann doch erst morgen.

Die Doku pass ich dann auch an.

Benutzeravatar
dr.e.
Administrator
Beiträge: 4555
Registriert: 04.11.2007, 16:13:53

Re: APF Coding Standard

Beitrag von dr.e. » 29.06.2014, 22:02:27

Perfekt, danke! :)

PS:
bisher hatte ich nie mit konflikten beim mergen zu tun :mrgreen:
Dabei kommt der Spass doch erst beim mergen! ;)
Viele Grüße,
Christian

dingsda
Beiträge: 49
Registriert: 03.02.2014, 04:00:36

Re: APF Coding Standard

Beitrag von dingsda » 30.06.2014, 01:31:07

dr.e. hat geschrieben:Perfekt, danke! :)

PS:
bisher hatte ich nie mit konflikten beim mergen zu tun :mrgreen:
Dabei kommt der Spass doch erst beim mergen! ;)
ich hatte zum glück sowieso erst gestern die aktuellen änderungen gepullt und daraus den branch erstellt daher waren nur 3 merge-konflikte. hab schon befürchte ich muss in allen 600 dateien nochmal korrigieren. das wär wirklich witzig geworden :mrgreen:

Antworten

Wer ist online?

Mitglieder in diesem Forum: 0 Mitglieder und 1 Gast