Coding standards

The naming of each file or directory in your system must be according to the following rules. The reason for this is the compatibility between different operating systems and their versions. MUST

» Allowed characters

The allowed file-naming characters are: MUST

• small characters of basic alphabet without any diacritics,
• in justified cases -> large characters of the basic alphabet without any diacritics (for example, components, objects and classes),
• digits (0 to 9),
• only in justified cases -> hyphen/em-dash (not en-dash, nor nonbreaking hyphen) (for example source file classes)
• underscore

These are the only symbols that you can use for file-naming.

Correct examples:

• _card-list.scss
• coding_standards_v01.docx
• 20171231_vyrocni_zprava.docx

Wrong examples:

• kódovací-standardy.docx
• coding standards.docx
• CodingStandardsV01.docs
• Coding_Standards_V01.docs
• 2018-01-01_vyrocni-zprava.docx
• 2018-01-01_vyrocni_zprava.docx

» File extensions

Except for a few special exceptions, files must have their correct extension, which corresponds to its structure (MIME type). The file extension is always written in lowercase. MUST

Correct examples:

• picture-with-people.jpg
• coding-standards.docx

Wrong examples:

• picture.JPG
• picture_one.JPG
• picture_one.jpg
• coding-standards.DOCX

Files without extensions are typically environment configuration files. Those files are subject to their own naming and structural conventions according to their use. For example: webconfing, .git, etc.

» Date in a filename

When a date is used in a name of a file, it is always formatted in order of year, then month and day, and without any hyphens. The reason for this is to maintain the correct sorting right from the file system level and further. The date is always at the beginning of the file name.MUST

Correct examples:

• 20180101_vyrocni_zprava.docx

Wrong examples:

• Výroční zpráva 1.1.2018.docx
• 18-1-1_vyrocni-zprava.docx
• vyrocni-zprava_180101.docx
• 2018-01-01_vyrocni-zprava.docx
• 2017-24-12_Vánoční přání.docx

» Filename length

Some of the operating systems have a limited filename length along with the length of the absolute file path. Therefore, the path length along with the filename must not exceed 260 characters. MUST

Web development projects term stands for any project that will be available to users via any web browser in one of their environments. The directory structure of these projects must be set properly according to the following rules. SHOULD

» Non-public sources

Non-public sources term stands for any of the files and folders that are not directly accessible through any URL without passing through application logic. To prevent unauthorized access, these sources must be located outside the root of the site (DocumentRoot), ie. the directory to which the Internet domain is directed. Non-public sources are typically application source files, internal documents, and configuration files MUST

» Public sources = DocumentRoot

Public sources term stands for any files and folders provided to site visitors to view or download. Those files and folders are located inside the root directory of the site. Such sources are typically needed for correct page rendering (e.g., cascading styles known as CSS, JavaScript, images, fonts), downloads, and static HTML pages. MUST

» GIT directory structure:

• src – source codes
• build – re-compiled source code (do not use /dist)
• etc – configuration files (for some applications, apache/nginx such as http.conf, … )
• debian - for debian packag
• service - for daemontools scripts (application run)
• bin - scripts
• www - document root apache/nginxe
• test/postman - api texts/strings for postman
• test/selenium - selenium tests
• test/unit - unit tests

» GIT directory structure example:

• /www/<PROJECTGROUP></<PROJECTNAME> application root (it is not a root vps/server)
  • app [755] – application directory
  • etc - configuration scripts (e.g. http.conf for apache/nginx)
  • log [775] - logs
    • http - logs for apache/nginx
  • vendor | node_modules [755] - third-party libraries directory (according to used technology)
  • www [755] – the root of the site, the domain is directed here
    • assets/css [775] - cascading style sheets (CSS) directory
    • assets/js [755] – JavaScript directory
    • assets/img [755] - images
    • assets/favicon [755] - favicons
    • assets/font[755] - fonts
    • data/upload [775] - a directory for uploading files through the application
  • README.md [644] – a file containing textual information about the project
  • composer.json [644] – configuration file
  • Makefile.app – a file containing info of ‚How to recompile the application?‘
• React
  • app – main directory
    • components – presentation components (show content only)
    • containers - components containing status or receiving data from the site
    • store - redux store, action, reducers
    • utils - helpers
  • www - assets which will be added to the built-in application

All third-party libraries are used as they are and are no longer modified in the application. Interference with library source code is not allowed. Libraries have to be uploaded to the project only via NPM (https://www.npmjs.com/). MUST

In any scenario, where an intervence with third-party library is necessary, it is highly recommended to rather copy its whole content and paste it straight into the project. From that point this potential library is not considered as a third-party library anymore. NOT RECOMMENDED

If a new internal library is created, the code must meet the following parameters:

• Purity and validity of its code, MUST
• Separately functional package (HTML, CSS cascading style sheets and JavaScript), SHOULD
• Complete Documentation including definition of inputs, outputs and links to external or any other internal libraries SHOULD
• Approval of the internal authority of the company MUST

Once such library is approved, it‘s is placed within the internal repository for potential usage.

This is a set of HTML code rules that helps to maintain good app rankings in search engines.

This chapter defines the rules for creating and generating the final HTML code, which is later sent to any browsers for displaying.

The HTML 5.2 https://www.w3.org/TR/html52/ is the standard used in the HTML code part of web applications. At the beginning of each page, it is necessary to create a so-called doctype by using the following tag:

<!DOCTYPE html> MUST

All individual HTML elements are always indicated by lowercase letters. RECOMMENDED

Correct examples:

• <table>
• <p>

Wrong examples:

• <Table>
• <TABLE>

Names of any element attributes are always in lowercase. RECOMMENDED

Correct examples:

• <img src=”/image.jpg” alt=”image 1” title=”image 1”>
• <td colspan=”2” data-sortable=”false”>

Wrong examples:

• <td colSpan=”2”>
• <span data-myFancyAttribute=”1”>
• <td COLSPAN=”2”>

Names of any class and identifier are always compiled of lowercase letters of the elementary alphabet, hyphen, and underscore.

Correct examples:

• order--submit-buton
• submit-button

Wrong examples:

• orderButton
• tlačítko-objednávka

The whole code must be „well formed“ and „valid“ – without any errors or warnings. That means it must also comply with the rules of correct structure from the technical point of view (crossing of elements, closing of open elements) and also from the point of view of semantics (correct sequence, block elements are not included in non-block). SHOULD

Correct examples:

• <table><tbody><tr><td>1</td><td>2</td></tr></tbody></table>
• <p>

Wrong examples:

• <ul><li>Lorem<li>Ipsum<li>Dolor</ul>
• <strong><a href=”/link”>Lorem ipsum</strong></a>
• <img><strong>Lorem ipsum</strong></img>/li>
• <a><div>Lorem ipsum</div></a>

All elements, with some exceptions, must always have an opening and closing element. Joining is not allowed. The exceptions are <input>, <link>, <br>, <hr>, and <img>. Those are elements which do not have any enclosing parts. MUST

Correct examples:

• <p>Lorem</p><p></p><p>ipsum</p>
• <p>Lorem ipsum<br>dolor sit amet</p>
• <img src=”image.jpg” alt=”image”>

Wrong examples:

• <p>Lorem</p><p /><p>ipsum</p>
• <img src=”image.jpg” alt=”image”></img>
• <img src=”image.jpg” alt=”image” />

The final HTML code can be validated on the link https://validator.w3.org/ Some individual exceptions to ignore some of the rules can be negotiated in justified cases. For example the need to ignore the unauthorized namespace “xmlns: og“ which is required when linking to Facebook.

» Meta-information/metadata

Each page must contain the following information:

• a standard declaration at the beginning of a document <!DOCTYPE html>, MUST
• a correct title in the header between the tags <title>Page title</title>, which is not used repeatedly within other pages SHOULD
• correct language settings on the html tag, for example <html lang=”cs”>....</html>, SHOULD
• meta keywords OPTIONAL and meta description SHOULD , which are changed according to a page
• the header contains information about favicon in the recommended formats MUST
  • for android devices any png is in the dimensions of 192x192 pixels
  • for apple devices any png is in the dimensions of 180x180, 152x152, 144x144, 120x120, 114x114, 76x76, 72x72, 60x60, 57x57
  • for normal browsers any png is in the dimensions of 16x16, 32x32, 96x96
  • manifest with links to icons

» Headings structure

Each page must always contain one <h1> heading which content corresponds to the content of a page (it’s not static). Headings must be used properly and according to a tree structure without skipping any of the levels. MUST

Correct examples:

• h1
  • h2
  • h2
    • h3
    • h3
  • h2

Wrong examples:

• h1
  • h2
    • h4
  • h3
    • h4
    • h5

Headings are never separated at the lowest level in the element tree

Correct examples:

• <li><h2>Lorem ipsum></h2><p>Dolor sit amet</p></li>

Wrong examples:

• <li><h2>Lorem ipsum</h2></li>

» Semantic elements

Elements must be used correctly for their purpose and must have the correct attributes:

• images must always have set an attribute of alt =”...” MUST a title=”...” OPTIONAL
• Tables can be used only for data displaying, and can’t be used to create any application design MUST
• <em> and <strong> (instead of non-semantic <i> and <b>) tags are used to highlight a text SHOULD
• links must have set the attribute of title=”...” OPTIONAL
• non-site links must have set an attribute rel=”nofollow” OPTIONAL

» Social sites

The applications should have completed basic attributes for social networks according to the documentation available at http://ogp.me/ SHOULD The mostly supported social media platforms are Facebook and Twitter.

The list of these attributes is below:

• og:site_name
• og:type
• og:locale
• og:title
• og:description
• og:url
• og:image (jpg image in dimensions of 1200x630px)
• twitter:title
• twitter:description

» Robots.txt

The robots.txt file is located in the root directory where the domain is located. MUST This file contains a declaration of whether crawling and indexing is enabled on the site. It also includes a declaration and a path to the project sitemap. Also, it can contain declarations and disabling access of robots for example to an administration. Cascading style sheets (CSS) and JavaScripts are not disabled. You can find examples and further documentation at: http://www.robotstxt.org/

Example of robots.txt file content:

User-agent: *
Disallow:
Crawl-delay: 30
sitemap: sitemaps.xml

» Sitemap.xml

The sitemap.xml file is located in the site root directory. MUST This file typically contains only links to other sitemaps that already have specific content. The syntax and examples can be found and https://www.sitemaps.org/

Each declaration is valid by syntax, and the <lastmod> tag always and exclusively contains the date of creation of the page, not the date when the sitemap has been generated. If the site/project is focused on graphical content/resources, it is recommended to create an image sitemap.

TODO: add split to parts, such as categories, products, etc. Add lastupdate tag

Any site that display specific resources (such as a specific articles) should have MicroData listed. Microdata is embedded in HTML as elements and attributes. You can find the schema list is at http://schema.org/. The validity of the scheme can be verified on the online validator Available at https://search.google.com/structured-data/testing-tool?hl=cs

All product pages must contain Google Rich Snippets microdata to correctly show structured snippets such as price, manufacturer, ranking, vendor, and so on in the Google search results. More info about product microdata and implementation can be found at https://developers.google.com/search/docs/data-types/product the correctness of the implementation can be verified by https://search.google.com/structured-data/testing-tool/ MUST

Example of microdata implementation in HTML code:

<div itemscope itemtype="http://schema.org/Product">
<span itemprop="brand">ACME</span>
<span itemprop="name">Executive Anvil</span>
<img itemprop="image" src="anvil_executive.jpg" alt="Executive Anvil logo" />
<span itemprop="description">Sleeker than ACME's Classic Anvil, the
	Executive Anvil is perfect for the business traveler
	looking for something to drop from a height.
</span>
Product #: <span itemprop="mpn">925872</span>
<span itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">
	<span itemprop="ratingValue">4.4</span>
	stars, based on
	<span itemprop="reviewCount">89</span>
	reviews
</span>

<span itemprop="offers" itemscope itemtype="http://schema.org/Offer">
	Regular price: $179.99
	<meta itemprop="priceCurrency" content="USD" />
	$<span itemprop="price">119.99</span>
	(Sale ends <time itemprop="priceValidUntil" datetime="2020-11-05">
		5 November!</time>)
	Available from:
	<span itemprop="seller" itemscope itemtype="http://schema.org/Organization">
		<span itemprop="name">Executive Objects</span>
	</span>
	Condition:
	<link itemprop="itemCondition" href="http://schema.org/UsedCondition"/>Previously owned,
		in excellent condition
	<link itemprop="availability" href="http://schema.org/InStock"/>In stock! Order now!
</span>
</div>

										

For a purpose of other tools, it is strongly recommended to add unique identifiers to elements which have an important functional impact. For example, we add a “button-complete-order“ ID to the order completion button for an online store (eshop). The rules for creating identifiers should meet the html rules mentioned in this documentation. Thanks to this we will be able to very comfortably do things like for example:

• Add a conversion tracking with Google Tag Manager,
• Create a Selenium test which will be able to complete the order or
• Create a satisfaction questionnaire.

All cascading styles are stored in separate files outside the template, hence no inline styles are allowed. The only exceptions are when some parts of the design are dynamically generated (for example, background images ie the background-image css attribute). It is not allowed to overuse styles by using the !important declaration.

All cascading styles must be written in lowercase letters with dashes and without any diacritics. IDs must not be used as CSS selectors because they should be reserved for automatic application testing. MUST

Correct examples:

• .my-class-for-first-cell
• .header-cell

Wrong examples:

• .myClass
• .MYCLASS
• .my-class_first
• #small-image
• .moje-třída

Each CSS rule/attribute must be specified on its own line with and ended by semicolon. MUST

Zero-numeric values are set without any unit. SHOULD

Text values of any attribute are always placed within quotation marks. SHOULD

Correct examples:

• font-size: 12px;
• font-family: “Arial”;
• padding-bottom: 0;

Wrong examples:

• text-decoration: UNDERLINE;
• padding-bottom: 0px;
• font-size: 12px !important;

SASS is a library that brings known options from programming languages to the classic CSS. The CSS itself extends the possibility of using "variables", "expressions" and "mixins". In addition, in SASS, individual scripts can be nested in multiple levels (creating tree notation), which can reduce the amount of a written code. Basic mathematical operations can be used as well.

Unfortunately, the web browsers cannot process this code directly, so it is necessary to recompile it to pure CSS. The basic information about using the SASS preprocessor is available on the page http://sass-lang.com/guide.

When writing and modifying Bootstrap components – we have to use SCSS syntax (with parentheses). The ways of how to install the SASS preprocessor are listed on the page http://sass-lang.com/install.

» Variables

Variables can be used as constants with a fixed value or can be combined with each other. The name of the variable always starts with a dollar sign, followed by a name using the same rules as for pure CSS (using lowercase letters, dashes, without diacritics). After the name there must be a colon, then a value and finally a semicolon. MUST

Correct examples:

• $nice-blue: #5b83ad;
• .header { color: $nice-blue; }

Wrong examples:

• $niceBlue: #5b83ad;
• .header { color: $niceBlue; }

Variables must be used especially in the following cases:

• Color definitions,
• Defenitions of a size of letters,
• Font-family definitions
• Definition of a bootstrap container size (see below).

Correct examples:

• $color-red: #ff0000; .red { color:$color-red; }; .error { border-color: $color-red; }

Wrong examples:

• .red { color: #ff0000; }; .error { border-color: #ff0000; }

If there is a publicly available SASS source (URL) then for global variable definitions across the company for encoding is required to import this internal resource and use variables from this source. The SASS global definition reference should always be a part of the assignment.

» Mixins

The term of ‚mixin‘ can be understood as using a macro with a parameter (or without a parameter), which makes it easier to write browser prefixes for new CSS properties.

Example:

@mixin border-radius($radius) {
-webkit-border-radius: $radius;
-moz-border-radius: $radius;
-ms-border-radius: $radius;
border-radius: $radius; }

.box { @include border-radius(10px); }

» Compilation

To compile SASS files, we use the https://gruntjs.com/ grunt file, which you can install using the npm (node.js package manager) through the console:

$ npm install -g grunt-cli RECOMMENDED

» Structure

To make the source code easier to use, separate SASS and compiled CSS into separate directories and files according to their meaning MUST , so for example.:

• web projects:
  • src/sass
    • admin.scss – administration styling files
    • includes.scss - used to import the third-party libraries (bootstrap, jquery,…)
    • reset.scss - basic settings of the HTML elements
    • variables.scss - basic settings of the environment variables
    • mixins.scss – basic macros
    • styles.scss – custom styles for the application
  • assets/cs
    • styles.min.css
    • admin.min.css
    • reset.min.css

Therefore, it is possible to write custom styles to any file - typically styles.scss. At the beginning, only the includes.scss file is imported to ensure that all variables and libraries will be loaded correctly.

It is good to divide styles into scss files by context.

File naming suggestions:

• forms.scss – form elements rules
• slider.scss, tabs.scss - extra widgets rules
• typography.scss - rules for basic elements such as headings, bullets, or tables

» Third party resources import

Third-party libraries are imported right at the start of processing other SASS files so later they can be overloaded in subsequent SASS files. This is because it‘s not allowed to directly interfere with third-party scripts. RECOMMENDED

SASS import example:

@import "../../../node_modules/bootstrap/scss/bootstrap";

@import url('https://fonts.googleapis.com/css?family=Open+Sans:300,400,400i,600,700&subset=latin-ext');

										

↓ Bootstrap #

<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css">

<!-- Optional JavaScript paste before ending body tag  →
<!-- jQuery first, then Popper.js, then Bootstrap JS -->
<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js"></script>

											

↓ Rules for output #

↓ Graphic sources format #

↓ Icons #

↓ Images #

Only ECMAScript 5 is used for backward compatibility for browser viewing. It is not prohibited to save source code as ECMAScript 6 and use compilers (eg Babel) to translate it to a previous version that you need to send to the users.

Psat v ECMAScript 5

To check the quality assurance of the JavaScript code use JShint. MUST
Do not use jslint.

» Variables and functions names

All names of the variables and functions in JavaScript must be according to the so-called "camelCase" syntax, where the first letter is always small and each additional word is capitalized instead of using a space. The use of diacritics, dashes and underscores is not allowed. Variable names are written in English but comments can be in a different language.

Correct examples:

• var firstVariable = “variable”;
• function secondFunctionForTest(testParam) {}

Wrong examples:

• var first-variable = “variable”;
• var první proměnná = “variable”;
• var prvni_Promenna = “variable”;

There is always a space behind operators (= + - * /) and commas.
The code block indentation is made up of 4 spaces.

The output of the final website must meet the calidity of a HTML and CSS code according to W3C validator https://validator.w3.org/ JavaScript must be without any errors.

Automatic code check should be done using the online service of Codacy MUST

All web applications must be debugged for the following browser versions:

• Internet Explorer (version 11.0 a newer) + EDGE
• Firefox (at least two major versions after the current version at the date of application deployment) see more at https://www.mozilla.org/en-US/firefox/releases/
• Safari on MacOS (at least two major versions after the current version at the date of application deployment)
• Chrome (at least two major versions after the current version at the date of application deployment) see more here

These rules can be adjusted to the current application requirements.

Each version name has the following notation (accroding to https://semver.org/) MUST

X.Y.Z optionally X.Y.Z-AAA ( major.minor.patch )

• X - major version, increases when adding features which are not backward compatible
• Y - minor version, increases when adding features which are backward compatible
• Z - patch version (sometimes named as build), increases error corrections, ie merges, hotfixes which are backward compatible
• AAA - release note, eg alpha, beta, rc (release candidate), r (release). This note only makes sense when debugging packages for deployment, making pre-release packages, and so on.

Correct examples:

• v1.0.0
• v1.2.3-alpha
• v3.0.0