16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
84 lines
2.2 KiB
Plaintext
84 lines
2.2 KiB
Plaintext
== Why is this an issue?
|
|
|
|
Files that define symbols such as classes and variables may be included into many files. Simply performing that inclusion should have no effect on those files other than declaring new symbols. For instance, a file containing a class definition should not also contain side-effects such as ``++print++`` statements that will be evaluated automatically on inclusion. Logic should be segregated into symbol-only files and side-effect-only files. The type of operation which is not allowed in a symbol-definition file includes but is not limited to:
|
|
|
|
* generating output
|
|
* modifying ``++ini++`` settings
|
|
* emitting errors or exceptions
|
|
* modifying global or static variables
|
|
* reading/writing files
|
|
|
|
|
|
=== Noncompliant code example
|
|
|
|
[source,php]
|
|
----
|
|
<?php
|
|
|
|
print "Include worked!";
|
|
|
|
class foo {
|
|
// ...
|
|
}
|
|
----
|
|
|
|
|
|
=== Compliant solution
|
|
|
|
[source,php]
|
|
----
|
|
<?php
|
|
|
|
class foo {
|
|
|
|
public function log() {
|
|
print "Include worked!";
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
|
|
== Resources
|
|
|
|
* https://www.php-fig.org/psr/psr-1/[PHP-FIG Basic Coding Standard PSR1], 2.3 - Side Effects
|
|
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Refactor this file to either declare symbols or cause side effects, but not both.
|
|
|
|
|
|
'''
|
|
== Comments And Links
|
|
(visible only on this page)
|
|
|
|
=== on 10 Oct 2014, 18:56:40 Ann Campbell wrote:
|
|
\[~linda.martin] see what you think now.
|
|
|
|
=== on 13 Oct 2014, 11:59:00 Linda Martin wrote:
|
|
\[~ann.campbell.2] Explanation is great IMO. I just have 3 comments:
|
|
|
|
|
|
* I would use the word *evaluated* instead of *executed* in the sentence _"should not contain ``++print++`` statements that will be *executed* automatically on inclusion"_
|
|
* "side-effects" is present in the title but not in the description, I think it would be worth to mention it just be clear on its meaning.
|
|
* I would add a bullet point with "..." jus to be clear that the list is not exhaustive, even if you used the word "include".
|
|
Thanks!
|
|
|
|
=== on 14 Oct 2014, 14:22:47 Ann Campbell wrote:
|
|
\[~linda.martin] okay
|
|
|
|
=== on 15 Oct 2014, 07:26:24 Linda Martin wrote:
|
|
\[~ann.campbell.2] perfect! Thanks.
|
|
|
|
=== on 21 Oct 2014, 15:23:17 Linda Martin wrote:
|
|
\[~ann.campbell.2] FYI I added PSR-1 tag.
|
|
|
|
endif::env-github,rspecator-view[]
|