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.
Megger
Beiträge: 1233
Registriert: 04.11.2008, 10:57:37

APF Coding Standard

Beitrag von Megger » 09.12.2011, 13:02:57

Diskussion zur Wiki Seite
http://wiki.adventure-php-framework.org ... g_Standard
-----
Auf der Seite könnte man doch auch mal die grundlegende Ordnerstruktur vorstellen, oder nicht?
Ist natürlich jedem selbst überlassen, wie man sein eigenes Projekt strukturiert, aber das könnte man ja theoretisch als "Leitfaden" oder so sehen.
Zum Beispiel

Code: Alles auswählen

/biz
      /actions
/data
      /setup
/pres
      /documentcontroller
      /taglibs
      /templates
Außerdem kann man noch aufführen, was grundlegend in einem Kommentar stehen sollte (author, version usw.)
Tutorial: Browsergame mit dem APF (Die ersten Parts handeln von Installation und Inbetriebnahme des APFs, deswegen sicherlich auch für alle Nicht-Browsergame-Programmierer interessant)

APF-Version
  • Entwicklung: 2.0
  • Produktiv: 1.15

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

Re: APF Coding Standard

Beitrag von dr.e. » 27.12.2013, 21:58:06

Hallo zusammen,

vorneweg: ich liebe Standards! ;) 8-)

Gerne können wir auch auf der von Tobi vorgeschlagenen Ebene Guidelines erstellen. In erster Linie sind Coding Guidelines für mich jedoch eine Einigung darüber, ...
  • ...wie wir die Code-Basis allgemein strukturieren,
  • ...wie der Quelltext eingerückt und strukturiert sein soll,
  • ...dass in einem File immer der Lizenz-Header mitgeliefert weren muss,
  • ...der Namespace in der ersten Zeile steht,
  • ...nur Dateien gleicher Lizenz in das Release aufgenommen werden dürfen und externe Dateien immer eine Zulieferung/Konfiguration des Anwenders voraussetzen (siehe JSMin),
  • ...etc.
Ich kann zu diesem Thema (Tracker-Eintrag http://tracker.adventure-php-framework. ... .php?id=93) gerne einen Vorschlag aufschreiben. Im Wesentlichen sind es jedoch nicht so viele Themen.

Input von eurer Seite (abgesehen von den Tracker-Kommentaren)?
Viele Grüße,
Christian

Benutzeravatar
jwlighting
Beiträge: 466
Registriert: 14.07.2010, 14:23:58
Wohnort: LK Oldenburg
Kontaktdaten:

Re: APF Coding Standard

Beitrag von jwlighting » 26.01.2014, 13:25:32

So, bevor das Thema wieder einschläft, folgender Vorschlag:
Wir posten alle mal einen Screenshot von unseren Coding Style Einstellungen in PhpStorm (oder einer anderen IDE). Dann können wir vergleichen und uns auf einheitliche Einstellungen einigen.

Andere Dinge wie zum Beispiel die Lizenzheader und der Namespace in der ersten Zeile bedürfen imho keiner Diskussion mehr?!


Meine Einstellungen im Anhang.


LG :)
Jan
Dateianhänge
wrapping-braces-1.png
wrapping-braces-1.png (100.03 KiB) 5282 mal betrachtet
wraping-braces-2.png
wraping-braces-2.png (99.87 KiB) 5282 mal betrachtet
tabs-indents.png
tabs-indents.png (23.36 KiB) 5282 mal betrachtet
spaces-2.png
spaces-2.png (88.88 KiB) 5282 mal betrachtet
spaces-1.png
spaces-1.png (96.56 KiB) 5282 mal betrachtet
phpdoc.png
phpdoc.png (44.28 KiB) 5282 mal betrachtet
other.png
other.png (46.33 KiB) 5282 mal betrachtet
blank-lines.png
blank-lines.png (40.97 KiB) 5282 mal betrachtet
arrangement.png
arrangement.png (57.4 KiB) 5282 mal betrachtet

Menschen irren - Politiker sind Menschen.
Für den Norddeutschen ist 1kW = 2 Pfund Schlick.

jprangenberg
Beiträge: 410
Registriert: 16.08.2010, 22:14:54

Re: APF Coding Standard

Beitrag von jprangenberg » 27.01.2014, 09:28:40

Meine Einstellungen habe ich nicht verändert. Default PHPStorm Einstellung!

Benutzeravatar
Screeze
Beiträge: 1920
Registriert: 05.08.2009, 09:49:04
Kontaktdaten:

Re: APF Coding Standard

Beitrag von Screeze » 27.01.2014, 13:56:00

Habe ebenfalls Default.

Aber:
Ich wäre für das Verbannen von "private" bei Funktionen und Klassenmembern, das hindert an manchen Stellen die wiederverwendung von APF Code durch Vererbung, sodass man ganze Klassen kopieren muss, obwohl man nur in einer von 10 Funktionen 2 Zeilen austauschen müsste für den eigenen Anwendungsfall.
Ich finde "protected" sollte für ein Framework das kleinste Level sein im Normalfall.

Benutzeravatar
jwlighting
Beiträge: 466
Registriert: 14.07.2010, 14:23:58
Wohnort: LK Oldenburg
Kontaktdaten:

Re: APF Coding Standard

Beitrag von jwlighting » 28.01.2014, 21:27:53

Mag einer von euch Screenshorts von den Defaults oder zumindest die Unterschiede zu meinen Einstellungen herausfinden und posten?

Private Eigenschaften/Funktionen zu vermeiden/zu verbieten finde ich übrigens auch sehr sinnvoll. Genauso sollten auch (bis auf wenige Ausnahmen) Eigenschaften immer protected sein, und über Getter/Setter darauf zugegriffen werden. Dies fördert ebenfalls die Wiederverwendbarkeit, da sich die Klassen/Funktionen in den Gettern und Settern bei bedarf auf die eigne Anwendung adaptieren lassen, ohne dafür extra einen Adapter implementieren zu müssen - auch nur über Vererbung.

LG :)
Jan

Menschen irren - Politiker sind Menschen.
Für den Norddeutschen ist 1kW = 2 Pfund Schlick.

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

Re: APF Coding Standard

Beitrag von dr.e. » 30.01.2014, 14:00:45

Hallo zusammen,

hier mein Input:
  • Use an indent of 3 spaces, with no tabs.
  • There MUST NOT be a hard limit on line length; the soft limit MUST be 120 characters; lines SHOULD be 80 characters or less.
  • PHP code must always be delimited by the full-form, standard PHP tags
  • For files that contain only PHP code, the closing tag ("?>") is never permitted. It is not required by PHP.
  • When present, the abstract and final declarations MUST precede the visibility declaration.
  • When present, the static declaration MUST come after the visibility declaration.
  • File header MUST include the APF license block
  • There MUST be one space after the control structure keyword.
  • There MUST NOT be a space after the opening parenthesis.
  • There MUST NOT be a space before the closing parenthesis.
  • There MUST be one space between the closing parenthesis and the opening brace.
  • Class declarations have their opening brace on the same line.
  • Only one class is permitted in each PHP file (in general). Exceptions apply.
  • Every class MUST have a documentation block.
  • Classes that extend other classes or which implement interfaces should declare their dependencies on the same line.
  • Any variables declared in a class must be listed at the top of the class, above the declaration of any methods.
  • Giving access to member variables directly by declaring them as public is permitted but discouraged in favor of accessor methods (set & get).
  • Methods inside classes must always declare their visibility by using one of the private, protected, or public modifiers
  • As with classes, the brace should always have their opening brace on the same line.
  • Every function must have a documentation block. The DocComment has to be directly above the method/class. No blank lines!
  • Documentation for getter/setter can be omitted since they are self-explantory
  • If a function or method may throw an exception, use @throws for all known exception classes.
  • Function arguments should be separated by a single trailing space after the comma delimiter.
  • Arguments with default values go at the end of the argument list.
  • When a string is literal (contains no variable substitutions), the apostrophe or "single quote" should always be used to demarcate the string.
  • When a literal string itself contains apostrophes, content containing single-quotes must be escaped.
  • Strings must be concatenated using the "." operator. A space must always be added before and after the "." operator to improve readability.
  • If namespaces are used the first line after the opening <?php has to be the namespace declaration. The declaration is followed by the license header after a newline use statements follow directly after the license block.
  • Variable names MUST be declared in $lowerCamelCase. Variable names may only contain alphanumeric characters. Underscores are not permitted.
  • Function names MUST be declared in lowerCamelCase().
  • For object-oriented programming, accessors for instance or static variables should always be prefixed with "get" or "set".
  • Function and Methods names may only contain alphanumeric characters. Underscores are not permitted.
  • Classes should be given descriptive names an should always begin with an uppercase letter.
  • Avoid prefixed class names and prefer using namespaces.
  • Constants should always be all-uppercase, with underscores to separate words.
  • Doc blocks should use @package for namespace declaration, @class for referring to the class the doc block is created for. @author and @version should be there for classes. @version should be multi-line with "<br />" tags at the end of each version line.
Zu euren Punkten:
Private Eigenschaften/Funktionen zu vermeiden/zu verbieten finde ich übrigens auch sehr sinnvoll. Genauso sollten auch (bis auf wenige Ausnahmen) Eigenschaften immer protected sein, und über Getter/Setter darauf zugegriffen werden. Dies fördert ebenfalls die Wiederverwendbarkeit, da sich die Klassen/Funktionen in den Gettern und Settern bei bedarf auf die eigne Anwendung adaptieren lassen, ohne dafür extra einen Adapter implementieren zu müssen - auch nur über Vererbung.
Stimme ich nicht ganz zu. Sofern ein getter/setter vorhanden ist, der mindestens protected ist, brauchst du keine protected Variable. Wiederverwendbarkeit und Erweiterbarkeit steht bei Framework-Komponenten natürlich trotzdem im Vordergrund - da gehe ich absolut mit. Allerdings sollten wir hierbei immer das open close principle beachten.
Viele Grüße,
Christian

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

Re: APF Coding Standard

Beitrag von dr.e. » 05.02.2014, 23:30:07

Ich weiß, das waren viele Punkte von mir. ;) Gibts von eurer Seite noch weitere? Falls nein, schreibe ich die Wiki-Seite bei Gelegenheit.

Einspruch/Ergänzungen/etc. immer gerne!
Viele Grüße,
Christian

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

Re: APF Coding Standard

Beitrag von dr.e. » 16.02.2014, 09:18:37

Hallo zusammen,

darf ich um eure Rückmeldung bitten? Ich würde das Thema gerne bald abschließen. Danke! :)
Viele Grüße,
Christian

Benutzeravatar
jwlighting
Beiträge: 466
Registriert: 14.07.2010, 14:23:58
Wohnort: LK Oldenburg
Kontaktdaten:

Re: APF Coding Standard

Beitrag von jwlighting » 18.02.2014, 21:24:47

Hallo Christian,

sorry, ich bin noch dazu gekommen meine Einstellungen (siehe Screenshots) mit deiner langen Liste zu vergleichen. Habs aber auf dem Plan.

LG :)
Jan

Menschen irren - Politiker sind Menschen.
Für den Norddeutschen ist 1kW = 2 Pfund Schlick.

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

Re: APF Coding Standard

Beitrag von dr.e. » 19.02.2014, 02:14:22

Keinen Stress. Effektiv ist das mehr oder weniger die Standard-Einstellung, allerdings mit ein bisschen mehr Prosa. ;)
Viele Grüße,
Christian

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

Re: APF Coding Standard

Beitrag von dr.e. » 02.03.2014, 00:18:23

Hallo zusammen,

wie im APF-DEV-Chat diskutiert, kann die finale Coding Guideline unter http://wiki.adventure-php-framework.org ... g_Standard nachgelesen werden. Das Thema ist damit erledigt! :)
Viele Grüße,
Christian

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

Re: APF Coding Standard

Beitrag von dingsda » 20.05.2014, 15:43:09

hi,

meine frage passt denke ich hierher.
Wie steht das APF-team zum tag @inheritdoc für methode, die eine bereits dokumentierte methode überschreiben? z.b. wenn ein interface implementiert wird.
ist mir gerade beim database layer refactoring aufgefallen, dass da bei jeder datenbank-klasse die methoden teilweise leicht unterschiedliche Beschreibungen haben obwohl sie ja doch das selbe tun. die beschreibungen und parameter synchron zu halten ist auch recht aufwendig, daher bietet sich @inheritdoc doch an.
dürfte auch eigentlich von allen guten IDEs unterstützt werden. bei phpStorm und netbeans zumindest machen keine probleme und auch doxygen holt sich für die doku die infos die es braucht.

anderes thema sind die tags @private, @protected usw.
sollten ja nicht mehr nötig sein, seit php die angabe bei der methoden und properties unterstützt. sollen die trotzdem in den doc block rein oder können die weggelassen werden?

lg
dingsda

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

Re: APF Coding Standard

Beitrag von dr.e. » 23.05.2014, 19:29:47

Hi,
Wie steht das APF-team zum tag @inheritdoc für methode, die eine bereits dokumentierte methode überschreiben?
Mein Ansatz ist bisher immer überschriebene Methoden oder Methoden, die eine Interface implementieren nicht zu dokumentieren. Das ist nicht 100% durchgezogen und manchmal auch nicht sinnvoll. Insofern ist @inheritdoc zu nutzen eine gute Idee.
anderes thema sind die tags @private, @protected usw.
sollten ja nicht mehr nötig sein, seit php die angabe bei der methoden und properties unterstützt. sollen die trotzdem in den doc block rein oder können die weggelassen werden?
Aktuell haben wir uns dazu entschieden, diese einzufügen. Die API-Dokumentation wird mit doxygen generiert und doxygen benötigt die Angaben (soweit ich weiß).
Viele Grüße,
Christian

Benutzeravatar
jwlighting
Beiträge: 466
Registriert: 14.07.2010, 14:23:58
Wohnort: LK Oldenburg
Kontaktdaten:

Re: APF Coding Standard

Beitrag von jwlighting » 25.05.2014, 12:55:16

Die API-Dokumentation wird mit doxygen generiert und doxygen benötigt die Angaben (soweit ich weiß).
Sollte das nicht der Fall sein, sind sie allerdings doppelte Information, dann würde ich sie lieber weglassen ...

Menschen irren - Politiker sind Menschen.
Für den Norddeutschen ist 1kW = 2 Pfund Schlick.

Antworten

Wer ist online?

Mitglieder in diesem Forum: 0 Mitglieder und 1 Gast