OC Coding Style: Unterschied zwischen den Versionen

Aus Opencaching-Wiki
Zur Navigation springen Zur Suche springen
K
(fixed some syntax errors at ends of SQL-Strings)
 
(16 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
Hier werden die style-guidelines für die Entwickler des OC-Codes fortgeschrieben, diese Seite ist unvollständig und enthält derzeit nur einzelne Teile, die aus dem bestehenden Code übernommen wurden, bzw. auf den sich das Entwicklerteam geeinigt hat. Diskussionen hierzu sollten im [http://forum.opencaching-network.org/index.php?board=43.0 Entwickerforum] geführt werden.
+
The following rules apply to all developers who contribute source code to the Opencaching.de project. This documentation is incomplete / work in progress.
  
Allgemein sollen die Richtlinien aus [http://www.php-fig.org/psr/psr-1/ PSR-1] und [http://www.php-fig.org/psr/psr-2/ PSR-2] angewendet werden. Für die meisten Entwicklungsumgebungen gibt es auch Plugins, die auf die Einhaltung prüfen und somit für einen sauberen Code sorgen.
+
== General rules ==
 +
All source code files must
 +
* not contain TAB characters,
 +
* use 4-char indenting columns,
 +
* be UTF-8 encoded without byte order marks,
 +
* use only LF as line ends, with the current exception of [[Entwicklung/Codedoku#Email-Templates|email templates]], which have RFC-822 CR/LF line ends.
  
Für die Einrückung sollen 4 Leerzeichen verwendet werden - keine Tab-Stopps!
+
There are some tools in the [https://github.com/OpencachingDeutschland/oc-server3/tree/master/local/devel local/devel] directory for verifying and fixing these things.
  
Um den Composer-Autoloader nutzen zu können, müssen Klassen nach [http://www.php-fig.org/psr/psr-4/ PSR-4] benannt und in die bestehende Namespace-Struktur einsortiert werden.
+
== PHP ==
 +
All contributed or modified code sections must fully comply to the [http://www.php-fig.org/psr/psr-2/ PSR-2] standard (which includes [http://www.php-fig.org/psr/psr-1/ PSR-1]), with these exceptions:
  
[[Kategorie:Entwicklung|Stil]]
+
* When referencing identifiers (e.g. class and function names) that are defined in non-PSR-2-compliant source code files, their names need not be PSR-2 compliant.
 +
* When writing standalone scripts like those in the 'local', 'util' and 'util2' directories, they need not to comply to the PSR-1 "Side Effects" rule.
 +
 
 +
Only <code><?php</code> and <code><?=</code> open tags must be used. <code><?</code> (short open tags) must not be used.
 +
 
 +
== SQL ==
 +
See also: [[Entwicklung/Codedoku#Datenbank]]
 +
 
 +
All SQL language elements are written in CAPS, and all user-defined identifiers in `backticks`. Inner joins are coded as JOIN and not as WHERE. All variable values inserted into SQLs '''must''' be escaped, either via placeholders like <code>'&1'</code> or via function <code>sql_escape()</code>.
 +
 
 +
SQL code inserted into PHP code is enclosed in double quotes and generally formatted like this:
 +
 
 +
    $result = sql(
 +
        "SELECT `cache_id`, `wp_oc`
 +
        FROM `caches`
 +
        JOIN `cache_logs` ON `cache_logs`.`cache_id` = `caches`.`cache_id`
 +
        WHERE `caches`.`status` IN ('&1', '&2')",
 +
        $status1,
 +
        $status2
 +
    );
 +
 
 +
Note that the opening " is on a tab position, while the following lines start one column to the right.
 +
 
 +
If lines get too long, the parameters are moved to the next line(s) and indented to the next indent column (which is ''three'' chars right of the preceding line's keyword):
 +
 
 +
    $result = sql(
 +
        "SELECT
 +
            `caches`.`cache_id`,
 +
            `caches`.`type` AS `cache_type`,
 +
            `cache_logs`.`date` AS `log_date`,
 +
            `cache_logs`.`type` AS `log_type`
 +
        FROM `caches`
 +
        JOIN `cache_logs`
 +
            ON `cache_logs`.`cache_id` = `caches`.`cache_id`
 +
            AND `cache_logs`.`type` = '&1'
 +
        WHERE
 +
            `caches`.`status` = '&2'
 +
            AND `cache_logs`.`user_id` = '&3'",
 +
        $logType,
 +
        $cacheStatus,
 +
        $userId
 +
    );
 +
 
 +
[[Kategorie:Entwicklung|Coding Style]]
 +
[[Kategorie:English pages]]

Aktuelle Version vom 29. August 2016, 12:28 Uhr

The following rules apply to all developers who contribute source code to the Opencaching.de project. This documentation is incomplete / work in progress.

General rules

All source code files must

  • not contain TAB characters,
  • use 4-char indenting columns,
  • be UTF-8 encoded without byte order marks,
  • use only LF as line ends, with the current exception of email templates, which have RFC-822 CR/LF line ends.

There are some tools in the local/devel directory for verifying and fixing these things.

PHP

All contributed or modified code sections must fully comply to the PSR-2 standard (which includes PSR-1), with these exceptions:

  • When referencing identifiers (e.g. class and function names) that are defined in non-PSR-2-compliant source code files, their names need not be PSR-2 compliant.
  • When writing standalone scripts like those in the 'local', 'util' and 'util2' directories, they need not to comply to the PSR-1 "Side Effects" rule.

Only <?php and <?= open tags must be used. <? (short open tags) must not be used.

SQL

See also: Entwicklung/Codedoku#Datenbank

All SQL language elements are written in CAPS, and all user-defined identifiers in `backticks`. Inner joins are coded as JOIN and not as WHERE. All variable values inserted into SQLs must be escaped, either via placeholders like '&1' or via function sql_escape().

SQL code inserted into PHP code is enclosed in double quotes and generally formatted like this:

   $result = sql(
       "SELECT `cache_id`, `wp_oc`
        FROM `caches`
        JOIN `cache_logs` ON `cache_logs`.`cache_id` = `caches`.`cache_id`
        WHERE `caches`.`status` IN ('&1', '&2')",
       $status1,
       $status2
   );

Note that the opening " is on a tab position, while the following lines start one column to the right.

If lines get too long, the parameters are moved to the next line(s) and indented to the next indent column (which is three chars right of the preceding line's keyword):

   $result = sql(
       "SELECT
           `caches`.`cache_id`,
           `caches`.`type` AS `cache_type`,
           `cache_logs`.`date` AS `log_date`,
           `cache_logs`.`type` AS `log_type`
        FROM `caches`
        JOIN `cache_logs`
           ON `cache_logs`.`cache_id` = `caches`.`cache_id`
           AND `cache_logs`.`type` = '&1'
        WHERE
           `caches`.`status` = '&2'
           AND `cache_logs`.`user_id` = '&3'",
       $logType,
       $cacheStatus,
       $userId
   );