commit d289f82260422570a762621d83fdf562a555b99c
parent 347463e3fda3310f89a9bbffc067d47c03fc9d77
Author: finwo <finwo@pm.me>
Date: Wed, 15 Aug 2018 18:06:04 +0200
Working on javascript style spec
Diffstat:
| A | spec/spec0001.txt | | | 626 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 626 insertions(+), 0 deletions(-)
diff --git a/spec/spec0001.txt b/spec/spec0001.txt
@@ -0,0 +1,626 @@
+Specification: 0001 Robin Bron
+ Ratus B.V.
+ August 2018
+
+
+ Javascript Styling
+
+Copyright Notice
+
+ This document is licensed under a
+ Creative Commons Attribution 4.0 International License
+
+ You should have received a copy of the license along with this work.
+ If not, see <http://creativecommons.org/licenses/by/4.0/>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bron [Page 1]
+SPEC 0001 Javascript Styling August 2018
+
+Table of contents
+
+ 1. Introduction .................................................. 3
+ 1.1. Conventions .............................................. 3
+ 2. Source file basics ............................................ 3
+ 2.1. File name ................................................ 3
+ 2.2. File encoding ............................................ 3
+ 2.3. Special characters ....................................... 3
+ 2.3.1. Whitespace characters ............................... 3
+ 2.3.2. Special escape sequences ............................ 3
+ 2.3.3. Non-ASCII characters ................................ 3
+ 3. Formatting .................................................... 4
+ 3.1. Braces ................................................... 4
+ 3.1.1. Control structures .................................. 4
+ 3.1.2. Non-empty blocks .................................... 4
+ 3.1.3. Empty blocks ........................................ 4
+ 3.2. Indentation .............................................. 4
+ 3.3. String literals .......................................... 4
+ 3.4. Number literals .......................................... 5
+ 3.5. Array literals ........................................... 5
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bron [Page 2]
+SPEC 0001 Javascript Styling August 2018
+
+1. Introduction
+
+ This document serves as the complete definition of the coding
+ standards for source code in the JavaScript programming language as
+ followed by TrackThis. A JavaScript source file is described as
+ being "in TrackThis style" if, and only if, it adheres to the rules
+ herein.
+
+ Like other programming style guides, the issues covered span not
+ only aesthetic issues of formatting, but other types of conventions
+ or coding standards as well. However, this document focuses
+ primarily on the hard-and-fast rules that we follow universally, and
+ avoids giving advice that isn't clearly enforceable (whether by
+ human or tool).
+
+1.1. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ RFC2119 when, and only when, they appear in all capitals, as shown
+ here.
+
+2. Source file basics
+
+ 2.1. File name
+
+ File names MUST be all lowercase and may include underscores (_)
+ or dashes (-), but no additional punctuation. The extension MUST
+ always be ".js".
+
+ 2.2. File encoding
+
+ Source files MUST always be encoded according to the UTF-8
+ standard (See RFC3629).
+
+ 2.3. Special characters
+
+ 2.3.1 Whitespace characters
+
+ Aside from the line-feed character, the ASCII (See RFC20)
+ horizonal space character (0x20) is the only whitespace
+ character that appears anywhere in a source files.
+
+ 2.3.2. Special escape sequences
+
+ For any character that has a special escape sequence, that
+ sequence SHOULD be used rather than the corresponding numeric
+ escape sequence. Legacy octal escapes MUST NOT be used.
+
+ 2.3.3. Non-ASCII characters
+
+ For the remaining non-ASCII characters, either the actual
+ Unicode character or the equivalent hex or Unicode escape is
+ used, depending only on which makes the code easier to read
+ and understand.
+
+Bron [Page 3]
+SPEC 0001 Javascript Styling August 2018
+
+3. Formatting
+
+ 3.1. Braces
+
+ 3.1.1. Control structures
+
+ Braces are REQUIRED for all control structures (i.e. if, else,
+ for, do, while, as wel as any others). The first statement of
+ a non-empty block MUST begin on its own line.
+
+ Control structures SHOULD omit braces and be written on a
+ single line if the both the statement and the control
+ structure can be kept on a single line without wrapping when
+ it improves readability.
+
+ 3.1.2. Non-empty blocks
+
+ Braces follow the Kernighan and Ritchie style
+ ("Egyptian brackets") for non-empty blocks and block-like
+ structures.
+
+ - No line break before the opening brace
+ - Line break after the opening brace
+ - Line break before the closing brace
+ - Line break after the closing brace if that brace terminates
+ a statement or the body of a function or class statement, or
+ a class method. Specifically, there is no line break after
+ the brace if it is followed by "else", "catch", "while", or
+ a comma, semicolon, or right-prarenthesis.
+
+ 3.1.3. Empty blocks
+
+ An empty block or block-like construct SHOULD be closed
+ immediately after it is opened, with no characters, space, or
+ line break in between, unless it is part of a multi-block
+ statement.
+
+ 3.2. Indentation
+
+ Each time a new block or block-like construct is opened, the
+ indent increases by two spaces. When the block ends, the indent
+ returns to the previous indent level. The indent level applies to
+ both code and comments throughout the block.
+
+ 3.3. String literals
+
+ Ordinary string literals SHOULD be delimited with single quotes
+ (') and MUST NOT span multiple lines.
+
+ To prevent complex string concatenation, template strings
+ (delimited with `) SHOULD be used. Template strings MAY span
+ multiple lines in which case they SHOULD adhere the indent level
+ of the enclosing block if the whitespace does not affect
+ functionality or complicates the code.
+
+
+
+Bron [Page 4]
+SPEC 0001 Javascript Styling August 2018
+
+ 3.4. Number literals
+
+ Numbers may be specified in decimal, hexidecimal, octal or
+ binary. Use exactly "0x", "0o" and "0b" prefixes, with lowercase
+ characters, for hex, octal and binary respectively. Never include
+ a leading zero unless it is immediately followed by "x", "o" or
+ "b".
+
+ 3.5. Array literals
+
+ Array literals SHOULD include a trailing comma whenever there is
+ a line break between the final element and the closing bracket.
+
+ The variadic Array constructor MUST NOT be used for creating a
+ new array, unless used for allocating an empty array of a given
+ length.
+
+ Do not define or use non-numeric properties on an array
+
+
+
+Bron [Page 5]
+SPEC 0001 Javascript Styling August 2018
+
+
+ [JSGUIDE] Google JavaScript Style Guide
+ https://google.github.io/styleguide/jsguide.html
+
+ [RFC20] ASCII format for Network Interchange
+ Vint Cerf
+ https://tools.ietf.org/html/rfc20
+
+ [RFC2119] RFC Key Words
+ S. Bradner
+ https://tools.ietf.org/html/rfc2119
+
+ [RFC3629] UTF-8
+ F. Yergeau
+ https://tools.ietf.org/html/rfc3629
+
+Bron [Page N]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+SPEC 0000 Specification Format August 2018
+
+
+
+1. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+ "OPTIONAL" in this document are to be interpreted as described in
+ RFC2119 when, and only when, they appear in all capitals, as shown
+ here.
+
+2. Character Encoding
+
+ Plain-text files for specifications must use the CP437 standard with
+ the exclusion of character code 0x0A which represents a line feed as
+ specified in RFC20.
+
+3. Line definition
+
+ A line of text is a sequence of 0 or more characters followed by a
+ line feed character. For the sake of and clarity, the ending line
+ feed character is part of the line.
+
+ Lines are not allowed to be longer than 72 characters, including the
+ ending line feed character. A line is called a blank line if it
+ consists of only a line feed charachter.
+
+3.1. Line numbering
+
+ To ensure the following page dimension section is clear, we need to
+ define how lines are numbered.
+
+ Assuming a document is in digital format[1] and has a length of
+ greater than 0 bytes, the first character in the document is part of
+ line 0. Numbering lines from 0 instead of 1 gives us an advantage of
+ clarity in the next section.
+
+4. Pages
+
+ A page is a sequence of 60 lines. That means for every line number
+ n, the line is the start of a new page when n mod 60 = 0.
+
+4.1 Page header
+
+ The first line of a page must consist of a left-aligned spec number
+ indicator, a centered (short) document title and a right-aligned
+ publishing date (see 6.3). The second line of a page must always be
+ blank.
+
+4.2 Page footer
+
+ The last line of a page must consist of a left-align last name of
+ the author and a right-aligned page number between square brackets.
+ The second-to-last line of a page must be blank, just like the
+ second line of a page.
+
+
+
+
+
+Bron [Page 3]
+SPEC 0000 Specification Format August 2018
+
+5. Paragraphs
+
+ A paragraph is a sequence of consecutive lines containing characters
+ other than only a line feed. Paragraphs are separated by either a
+ blank line or a page break. Paragraphs are not allowed to span
+ multiple pages, limiting their size to 56 lines.
+
+6. Document header
+
+ The first lines of the first page of a specification document shall
+ always contain left-aligned description headers (see 6.1) and
+ right-aligned author identification and a right-aligned publishing
+ date.
+
+ Ensuring 2 blank lines between the initial lines (see 6.1 to 6.3)
+ and other text on the page, the document title (see 9) should be
+ noted in the top-middle of the first page of the document. Further
+ information on the first page should give a quick description of the
+ contents of the document.
+
+6.1. Descriptive header
+
+ Each descriptive header is made up of a key and a value. Whitespace
+ is not allowed in both the key and the value. Whitespace can only be
+ included in the value by wrapping the value in quote characters.
+
+ The key of the header consists of all characters of the line up to
+ the first semicolon, excluding the semicolon itself and omitting all
+ white-space characters.
+
+ The value of the header starts at the first non-whitespace character
+ after the first semicolon of the line. If the first character is a
+ quote, the value ends at the next quote in the line. If the first
+ character is not a quote, the value ends at the next whitespace
+ character.
+
+6.2. Short author identification
+
+ In order to allow authors to take some credit and to track who has
+ written what, the author's name must be added right-aligned on the
+ first line of the first page of the document. To prevent mixing
+ notations between documents, the names should be written as only the
+ first letters of all given names in capitals, separated by dots, a
+ space and the Family name starting with a capital. When written by a
+ group of with a name, the short author identification string should
+ state the group's name.
+
+6.3. Publish date
+
+ Because a document is unlikely to have been written within a day, a
+ publish date is simply the month's name starting with a capital
+ followed by the year, both following the Gregorian calendar.
+
+
+
+
+
+Bron [Page 4]
+SPEC 0000 Specification Format August 2018
+
+7. Document footer
+
+ The document should close, starting on a new page, with all
+ informative resources which were used to write the document, noting
+ their keyword, document title it's author and if possible a URL to
+ the resource.
+
+ After the informative resources, the document should end with one
+ or several pages dedicated to the information of the author(s) and
+ if possible their contact information.
+
+8. Section titles
+
+ Section titles should be a short text about the subject the section
+ describes. Whether it is simply the keyword of what it explains, a
+ problem statement or other type of text is up to the author as long
+ as it's relevant to the section's body.
+
+ A section title must start with a capital character & not contain
+ any other capital letters, excluding where they are required in
+ names or abbreviations.
+
+9. Document title
+
+ The title of the document should clearly state the main subject of
+ the document and it's contents. Each word of the document title must
+ start with a capital character when noted as the title of the
+ document.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bron [Page 5]
+SPEC 0000 Specification format August 2018
+
+10. Informative resources
+
+ [CP437] IBM Code page 437
+ https://en.wikipedia.org/wiki/Code_page_437
+
+ [RFC20] ASCII format for Network Interchange
+ Vint Cerf
+ https://tools.ietf.org/html/rfc20
+
+ [RFC822] Standard for ARPA Internet Text Messages
+ David H. Crocker
+ https://tools.ietf.org/html/rfc822
+
+ [RFC1111] RFC Instructions
+ J. Postel
+ https://tools.ietf.org/html/rfc1111
+
+ [RFC2119] RFC Key Words
+ S. Bradner
+ https://tools.ietf.org/html/rfc2119
+
+ [RFC7322] RFC Style Guid
+ H. Flanagan
+ S. Ginoza
+ https://tools.ietf.org/html/rfc7322
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bron [Page 6]
+SPEC 0000 Specification format August 2018
+
+11. Author information
+
+ Name ....... Robin Bron
+ Nickname ... Finwo
+ EMail ...... robin@finwo.nl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bron [Page 7]
