# Code Standards for Cardschat
[](https://www.cardschat.com/)
**This document contain some of the good practices we should follow to keep our project clean and maintainable.
This is an extension of our [Company Code Standards and Guides](https://bitbucket.org/legendcorp/public-code-standards-and-guides/src/master/). We should comply with both _company_ and this _project specific_ standards.**
---
<br>
## 👷 Standards for **Architecture**
- From now on we should start using dedicated folders to store styles and scripts for the pages. Keeping everything inside vBulletin webtemplates will make everything very hard to maintain. Also, transition to the new platform would require going through each page and checking for any inline styles and scripts.
- When creating Plugins we should use only `exported_plugins` directory and follow instructions from the readme file (`exported_plugins/README.md`).
## 🧩 Standards for **Git**
- Commit messages should be done on every commit, no matter how small the change was.
- Commit messages should contain jira ticket number and what was changed exactly, eg. which folder, page, file or section of the page was changed. This will make code review process much easier.
- Commit messages should be capitalized, and in be in imperative tense, eg.:
```Add new assets to module for CCO-123...```
instead of
```adding new assets to module for CCO-123...```
- Commit message should start with a keyword describing what kind of update was implemented:
eg. `Add | Change | Fix | Remove`
- There should be specific commit for every change, eg. don't mix changes in different parts of the code. That can prevent us from reverting specific changes if necessary. There should be more smaller commits.
- Pull Requests (PR) should be made for all merges. At least 2 team devs should approve all PR. Approvers are responsible for the code if it's pushed to master.
- For every new feature we should create separate branch with: **name**, **ticket number** and **feature description**. Branches should be removed after merge, eg.:
`jakub-maksimowicz_CCO-123-feature-name`
For further info refer to this [article about good commit practices](https://chris.beams.io/posts/git-commit/)
## ♿ Standards for **Accessibility**
- **NEVER** use `span`, `p`, `div` or similar elements to make interactive UI controls. **ALWAYS** use `a` or `button` for those. Generic inline or block elements don't have any default functionalities like eg. keyboard support. Also, screen reader won't normally read those as links or buttons.
- Always provide text alternatives for UI controls with visual content like images or icons. Without this screen reader users will have no information about purpose of the element. This should be achieved by providing proper `aria-label` attribute on the element, or if applicable visual label.
- We should always provide proper labels for form inputs. They should never be replaced by `placeholder` attribute.
- Check if contrast of the page is sufficient. You can refer to this [contrast checker tool](https://webaim.org/resources/contrastchecker/). This will help not only visually impaired people, but all users.
- Check if all functionalities are accessible from keyboard.
- Avoid using the `tabindex` attribute with non-interactive elements to make something intended to be interactive focusable by keyboard input. Instead, use native HTML elements like `button` or `link`.
To learn more about Web Accessibility you can join our [`#accessibility-guild`
](https://rockit.chat/channel/accessibility-guild) Rockit channel.
## 🏛 Standards for **HTML**
- When applicable use proper HTML5 tags like eg. `main`, `section`, `article` or `nav`. Replacing those with generic `div` elements will affect various web related technologies, eg. RSS feed readers.
- Remember to keep proper heading hierarchy. This means don't skip heading levels and don't nest headings. Remember that [document outline was never implemented](https://adrianroselli.com/2013/12/the-truth-about-truth-about-multiple-h1.html).
- We should lazyload images whenever it's possible
- We should use relative path for internal scrollsmooth in links, so eg. `/page.php/#{id}` instead of `#{id}`
- For images and iframes that are below the fold we should use native [`loading="lazy"` attribute](https://web.dev/native-lazy-loading/). All new HTML should not use lazy loading libraries, but we should still use those for background images
If you are not sure what certain element does, [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML) is a great resource.
## 🎨 Standards for **CSS**
- For all new implementations we should use [BEM naming methodology](https://cssguidelin.es/#bem-like-naming). This will ensure that all of our work will be maintainable and reusable.
- We should never style elements using tag names. This will make our CSS unmaintainable quickly, especially when we have multiple stylesheets and each of them provides different styles for eg. `<a>` tags. We should always use `class` attribute to style new elements.
- For setting `font-size` we should use relative units like `rem` or `em`. This will make implementing designs much more logical. This is also important for accessibility, as this will not override users preferred text sizes.
- We don't have to use CSS prefixes that much. Most of the popular features like `flexbox`, `border-radius` or `animation` will work fine with modern browsers. We should only use prefixes while using non-standard features that wouldn't work otherwise like eg. `appearance` or `::scrollbar`.
## 🤹 Standards for **JavaScript**
- For all new implementations we should stop using util libraries like jQuery, and when it's possible use vanilla JavaScript. This will make transition to new platform much easier, and the page will not be dependant on external libraries. This can also make the page a bit faster.
- Make sure that JS feature you are working on wasn't implemented before. Use existing functions if possible. This will prevent us from having parts of code that are doing the same things.
- We should always leave comments describing all new functionalities. This will ensure that new developers will have some idea what certain parts are responsible for.
- Check if the functionality you are working on actually requires JavaScript. A lot of things can be done in pure HTML and CSS, eg. anchor links, smooth scroll.
## 🔨 Standards for **PHP**
- If possible we should always put PHP code into least amount of `<?php ?>` tags, so eg.:
```php
<?php
echo start_tag();
echo post_content();
echo end_tag();
?>
```
Instead of:<br>
```php
<?php echo start_tag(); ?>
<?php echo post_content(); ?>
<?php echo end_tag(); ?>
```
- We should always put semicolon at the end of each PHP tag.
- We should avoid rendering static HTML with echo methods. If it's necessary we should use [`sprintf()` method](https://www.php.net/manual/en/function.sprintf.php). Eg.:
```php
<div>
<p>
<?php echo post_content(); ?>
</p>
</div>
```
Or:<br>
```php
<?php
$content = post_content();
echo sprintf('<div><p>%s</p></div>', $content);
?>
```
Instead of:<br>
```php
<?php
echo '<div>';
echo '<p>';
echo post_content();
echo '</p>';
echo '</div>';
?>
```
- We should take caution when using `isset()` in conditions, eg.:
```php
<?php
$author = '';
if(isset($author)) {
echo sprintf('<div class="author"><p>%s</p></div>', $author);
}
?>
```
Above code will render empty `div` element. Using `!empty` in the condition would skip unnecesary rendering.
- For PHP mixed with HTML we should use following syntax in loops and conditions:
```php
if(): endif;
```
Eg.:
```html
<?php if(display_content()): ?>
<div class="content">
</div>
<?php endif; ?>
```
- For PHP without HTML in between we should use following syntax:
```php
if() {}
```
Eg.:
```php
<?php if(display_content()) {
echo content();
} ?>
```
## 📰 Standards for **Wordpress Development**
- Change only the files that are inside `/wp-content` directory. You should never edit core wordpress files.
- Never change any files through admin panel.
- For most things we can use hooks. Don't hardcode any data that can be replaced with Filter or Action.
- Use Child Themes for any template changes. This would prevent from overriding main template with updates.
- Make sure that you can't use any of installed plugins functions before you install a new one. Eg. we can replace most of our SEO plugins with just Yoast Seo.
- Remember to uninstall all plugins that you know won't be used anymore. This will prevent us from having lots of disabled plugins.
- Avoid using `if` statements for creating customized pages. Use Page Templates instead every time it's applicable.
- Remember to always describe what certain function in `functions.php` file does with a comment. This will help us keep the file clean and maintainable.
## 🚀 Future proofing
- We should introduce SASS preprocessor to make our CSS reusable. This would also make transition to the new platform easier.
- We should remove all unnecessary and outdated libraries. Good example is [`yahoo-dom-event.js`](https://www.cardschat.com/clientscript/yui/yahoo-dom-event.js), which is **2009** library, and most of it's functions are now in native JS implementation.
- As agreed, we should drop support for IE and focus on Chrome, Firefox and Safari. Supporting Internet Explorer can introduce few problems with implementing polyfills:
- Polyfills can be heavy which will cause longer loading time,
- Supporting IE can force us to use outdated CSS rules and JS API's which can become difficult to maintain,
- It can be very time consuming,
- Same goes for Microsoft Edge, as new Edge version will be chromium-based, we shouldn't worry about supporting it.
- **Exception to this is when some critical piece of functionality is broken**
<br>
---
<br>
Please contact [jakub.maksimowicz@itech.media](mailto:jakub.maksimowicz@itech.media) with any questions or feedback.
Google Drive
Gist
Clipboard
Sign in with Wallet
