General guidance

Prerequisites

Completed Docker install done. Frontend instructions.

Steps

• Once the theme has been cloned, CD into the root of the theme.
• Copy .envexample and rename it to .env, edit the file as per the comments.
• type npm install.
• npm start and you're good to go. This will set up a development environment for you.

Note: Depending on your Docker configuration, you may need to use rsync to port your changes across. See a member of the Intranet development team for correct Docker setup.

Best practice should be adhered to wherever possible. This part of the guide shows the best practice rules this project follows.

A function/method/mixin should only ever do one thing

When writing your code, look at what it's doing. If it's doing more than one thing, break it down into it's constituent parts and make sure all code is reusable. If something is specific to a component feel free to write it inside the component file but think long and hard about if this new code could be used elsewhere. If it can, it belongs in global.

Tab spacing should be uniform

In the PHP it should be 4 spaces per tab and in all other files it should be 2 spaces per tab. Note: This excludes markdown as it has it's own tab structure for formatting.

Stay DRY at all times.

DRY (Don't Repeat Yourself) is the best way to keep code from growing too complex. Before you write a new function/method/component/class find out if there is something that already exists that you can use or extend.

Terser is better (to a point)

If you can write something in 10 lines of code or 2 lines of code, try to aim for two lines. However make sure that what you write is still understandable to someone who is new to the code.

Document everything

Everything you write should be covered by documentation. This is especially true for new components as the documentation is how other developers know how to use them and where.

Note: CSS is very self-explanatory so more basic comments are acceptable here unless you are doing something out of the ordinary.

Code comments should be helpful

In relation to the above. Whenever you add code comments, make sure they are useful, try to follow Docblokr conventions where possible. Don't worry about comment lengths in front end code (CSS/JS) as these comments will be stripped out when they are minfied. Where it's relevent also try to tag your comments like so:

//TODO: This is something that needs to be done in the future (note: This should also be added to either tech debt or the project tracker)

//BUG: This is a bug that has been spotted but has not yet been fixed (note: This should also be added to either tech debt or the project tracker)

//HACK: If you have had to do something janky because you didn't have the time or ability to do it properly. Add this comment so it can be easily found in future refactors (Note: This should also be added to the tech debt)

//FIXME: This is broken code (not just a bug), it is primarily used if you are going to come back to it soon or if you want to flag it for another developer to take a look at.

//XXX: This is where other developers can highlight questionable code. It is useful in code reviews.

//LEGACY: This is being used whilst the legacy theme / child theme is in place and indicates code that should be removed/altered when the legacy theme is removed.

Note: All tags should be in capitals. Depending in your dev environment, your editor should pick up the above tags and highlight them. Some (Webstorm for example) can even find all the specific tags in a project so you can see a list of everything that needs to be done. Most IDE's and text editors which have a plugin architecture also have extensible support for these tags.