123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200 |
-
- // // // //
- // // //
- // ////// ////// // // // ////// ////// //////
- // // // // // // // // // ////// // //
- // // // ////// // ////// ////// ////// // //////
-
- Include.d is a library of classes, functions, and constants for
- inclusion in larger scripts. If you plan to make use of include.d, or
- especially if you plan to make pull requests to include.d, it could be
- helpful to understand the naming and other conventions we use here.
- == this file ==
- This file is meant as a plain text file. Gogs, the software used by
- Volatile Git and NotABug.og, mistakingly interprets it as a Markdown
- file on some pages and condenses the spacing on other pages. This file
- should be readable in either case, but is formated for view in a plain
- text viewer using a fixed-width font. Any mangling of the ASCII art
- above or strange line lengths when viewed using other methods are not
- something that can be fixed on our end.
- == licensing ==
- Include.d is released under the GNU GPLv3+. This fact MUST be included
- in the comments at the top of each class, function, and constant file.
- Individual files may instead be under a GNU GPL-compatible other
- license, but this license MUST be mentioned in the comments at the top
- of the file also or instead.
- == case insensitivity ==
- Unfortunately, PHP handles namespace, class, and function names in a
- case-insensitive manor. for compatibility with \spl_autoload(),
- namespace directories and class file names must be spelled using
- lower-case letters. For consistency between the file tree structure and
- the class files, this also means that namespace and class names are
- specified in lower case. Although functions cannot be autoloaded, for
- consistency, this rule applies to function names as well, though not
- necessarily method names. Because constant names are case-sensitive
- like they should be, files containing constants may contain upper- or
- lower-case letters, but the case much match what is declared in the
- file.
- == directory structure ==
- Include.d is structured such that if include.d is in your include path
- and you have run \spl_autoload_register() without any arguments,
- autoloading of classes will function without any further effort. This
- means that namespaces are mapped to directories of the same name and
- nested namespaces are mapped to nested directories. Class files are
- named "<class name>.php". Unfortunately, functions and constants are
- not automatically loadable. To keep them from accedentally being loaded
- when searching for a class of the same name, they are placed in
- subdirectories of their respective namespace directories. Constants are
- placed in the "const" directory and functions are placed in the
- "function" directory. Because the strings "const" and "function" are
- PHP keywords, they will not appear in any namespace path and will not
- be accidentally autoloaded. It also makes sense to have this extra
- directory because functions and constants are imported using "use
- function" and "use const" respectively, while classes (and namespaces)
- are imported using only the keyword "use". These functions and
- constants can be easily included in a script if include.d is in your
- include path by including
- "<namespace>/<'const' or 'function'>/<constant or function name>.php".
- == in-file limitations ==
- Each file may only define one class, function, or constant, and it must
- be the one that is expected given our file- and directory-naming
- conventions. If there is a set of related functions, they must either
- be split and placed in different files or must be made into class
- methods. If a group of constants is related, they COULD be implemented
- as class constants, but if no functions are involved, they SHOULD be
- implemented as a constant array. It is recommended that files ONLY
- include code for defining a given class, function, or constant and not
- include any function calls or variable assignments outside of a
- function/method/class definition. As function calls are discouraged,
- use of define() to define constants is discouraged and the const
- keyword is preferred.
- == namespacing ==
- All code within this library MUST be namespaced to prevent name
- collision with other libraries. The preferred namespace naming
- mechanism for code in this library is to use the segment-reversed name
- of a domain that the author controls. For example, if you control the
- domain "example.com.", your code should be placed within the
- \com\example namespace. Typically, when someone controls a domain name,
- they also control all subdomains of that domain, so the owner of
- "example.com." could also place code in the \com\example\subspace
- namespace. If you do not already have a domain name and do not want to
- pay yearly domain fees, you may generate an onion address (you do not
- have to actually put the onion address into use) or select a subdomain
- of the "local." TLD. Special-use domains are taken into account and the
- \localhost namespace is reserved for defining classes, functions, and
- especially constants that are different on a per-system basis. Such
- constants are useful for defining user settings, for example. Names in
- the root name space that are considered special, such as the function
- name "__autoload", are the exception to this. A special functionality
- shouldn't be avoided simply on the grounds that using it requires use
- of a name in the root namespace.
- <https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml>
- == namespace resolution ==
- Due to the way that namespaces are resolved when working from within a
- namespace, ALL function and constant names MUST be qualified or
- fully-qualified. Use of unqualified function and constant names within
- this library is prohibited.
- == errors ==
- All code in this library must assume that ANY error, even those as
- minor as E_WARNING, may lead to script termination. The "@"
- error-suppression operator does not change this fact and must not be
- used. Errors may be emitted if an error actually occurs, but they MUST
- NOT be emitted as part of normal execution. If needed, be sure to
- perform data checks before calling any functions within your functions
- instead of using the error-suppression operator.
- == coding conventions ==
- These conventions are not enforced, but if followed, will help our
- library look more unified.
- * When indenting code, tabs are preferred over spaces.
- * "if(): <...> endif;" is preferred over "if { <...> }". To be clear,
- this applies to all available "end*" keywords, not just "endif".
- * "/** **/"-style comments are preferred only to document code in
- phpDocumentor format.
- * "/* */"-style comments are preferred only in places where it's
- useful to place code after the comment on the same line. These
- comments shouldn't span multiple lines, as they look too much like
- documentation comments.
- * "//"-style comments are preferred for comments that shouldn't be
- rendered as documentation. These comments will probably be seen
- only by people looking at the code, and should be used anywhere in
- which we're writing notes to ourselves and other developers about
- why something is done or how it works, among other things.
- * "#"-style comments are preferred for commenting out lines that are
- otherwise valid code. Usually, this lines will probably be removed
- from the library, but they may be left in for future uncommenting
- or to show examples.
- == exception codes ==
- Every exception thrown from the include.d library has a unique
- exception code, which is potentially useful for debugging. To insure
- that exception codes are not reused, five- or six-character strings are
- encoded as integers using the \sy\y\string_to_code() function. The
- string is added to the known exception code registry and the integer is
- used as the exception code. This exception code registry is a file
- included in the debug code repository.
- == documentation ==
- All of our classes, methods, class constants, properties, functions,
- and constants are documented using phpDocumentor-style comments. At a
- minimum, classes, functions, and constants must use the @category,
- @package, @subpackage, and @since tags, where @since is the include.d
- version in which the named structure was added. Methods, class
- constants, and properties shouldn't use the @category, @package, and
- @subpackage tags, but must use the @since tag. Additionally, files must
- not throw errors when phpDocumentor builds documentation, at least not
- based on the comments or lack of information in the comments. To
- prevent errors, file-level documentation comments must be provided, but
- the file-level documentation should contain only the name of the
- library, the fact that it's under the GNU GPLv3+ (or whatever
- compatible license that that particular file is under), and the
- @category, @package, and @subpackage tags with values copied from the
- documentation of the named construct that the file contains.
- Additionally, the @author, @copyright, @filesource, and @license tags
- should be used, but no other phpDocumentor tags should be used in the
- file-level documentation.
- == version numbers ==
- When merging a branch with master, the version is incremented in the
- following way. The number of nested namespaces used by a new named
- structure is counted. If the structure is a class, not a constant,
- class constant, function, method or property, subtract one. If multiple
- new structures were added in the new version, take the structure that
- yields the smallest value. If no new named constructs were added,
- instead find the highest value produced with the preceding algorithm on
- existing structures and add one. Named constructs that cannot be
- \namespaced because of special names do not count for calculating this
- number.
- For example, if the class \org\example\example_class is added, the
- number would be two. If the function \org\example\example_function() is
- added, the number is three. If the method
- \org\example\subnamespace\sample::parse() is added, the number is four.
- After finding the number above, we increment the number in that
- component place in the version number and remove any less significant
- components. As the root namespace is not used by named constructs in
- this library outside of those with special names, the most significant
- version component, component zero, is never incremented. We will always
- be at version 0.*, we will never reach version 1.
- == To do lists ==
- Normally, when something needs to be done later, a note should be
- placed in an appropriate comment using a @todo tag, where phpDocumentor
- will find it and remind us of it. However, sometimes something needs to
- be done in a non-code file or needs to be done in a file that doesn't
- exist yet. In these cases, the @todo tag should be placed in the
- comment that documents the \st\y\VERSION constant. This constant
- contains information not about itself, but about include.d as a whole,
- so it can be used as a centralized place to place to store information
- that doesn't fit better in another part of the library when needed.
|