Rapido Conventions

Everyone who’s ever worked with code knows the challenges of creating maintainable code. Why do beautiful projects so often bloat into incomprehensible monsters?

Ultimately, all code projects start with the best of intentions – not even the most evil developer sets out to write incomprehensible or unmaintainable code.

So what can you do to keep the project maintainable over time?

  • Good names
  • Good comments
  • Simple statements
  • And above all - be consistent!

Here are some of the ground rules we’ve found most productive to focus on when developing projects based on Rapido.

When coding on an existing project – and since you’re using Rapido as a base, there will always be an existing project – you must code like the locals do, in each and every area. The rule is simple, when you are extending the code base, look at how things are already done, and then continue doing it that way.

This means that if you are using JavaScript and you notice that jQuery is not included, you must not include jQuery. If you do, the locals may get very aggressive indeed. Or if someone has organized the code in a way you do not like, do not change it, unless it is not done the same way as the rest of the code.

Actually, with time the locals will be yourself and your colleagues – and as a project matures it becomes increasingly important to do things the same way. You must align, learn to approach things from the same angle, and solve problems in the same manner, with respect for the local architecture.

So what do you do if you find two files within the same project with different approaches?

You generally have two options:

  • Treat each file as a village – and code in a manner true to the dialect used in each file
  • Treat the project as a village – and refactor the code whenever you discover a file which does not speak the project language

So what happens when a cool inventive villager like yourself discovers a fantastic new way to do something? Can you use it? YES! But…

  • All villagers – your colleagues – must agree that it’s a good idea
  • It should be used across the whole village – all over the project – replacing the current practice

Like all social norms this can be annoying at times, but if you don’t take this approach you will end up with a project filled with hundreds of different “smart” ways of doing more or less the same thing. So please take this approach – even when you have the greatest idea ever!

We strongly advise you to code like the locals do – or, as they say in Russia, you and the other villagers will eventually experience sadness.

A lot of stuff is possible with CSS, but to keep your CSS maintainable follow these simple rules:

  • The !Important attribute is highly illegal. There are very, very, very few circumstances where it is ok to use it – so don´t.
  • Nesting CSS is also almost always forbidden, as it can be very hard to know which rule overrides which rule. One of the few circumstances where it may be necessary is when manipulating font colors, as is done in the /base/base/_helpers.less class. Another example is when using checkboxes + css to show/hide content. See /base/components/_expandable.less
  • Try not to use Mixins - even though both Less and Sass supply the functionality. They make the code unnecessarily complex and hard to maintain, and it may be hard to convert it to the next popular language. The exception is when you want to use conditionals in Less – then Mixins are the only option.
  • Try to limit the use of the advanced features of the pre-compilers - this will make your code a lot more maintainable in the long run.
  • Use the prefix “js-” for any CSS class that JavaScript should grab. These classes may never, ever be styled. This makes it very visible that the classes are meant for JavaScript, and secures that we do not ruin them or use them wrongly
  • Don't use “markup styling” like <b>, <strong>, and &nbsp;. To keep the design consistent and maintainable, use css classes instead.

Base includes a lot of re-useable generic classes, which help you write maintainable code. The advanced classes are found in the “component” folder, while the most basic ones are found in “base/base/helpers.less”. The helpers have a “u-” prefix to show that it is a helper (Utility).

Keep names consistent. It sounds easy, but in reality it’s often the hardest task of all.

Here are the naming conventions in Rapido:

Type

Rule

Example

Note

HTML Element IDs

Each word must start with a capital letter (PascalCase).

id=”MySpecialElement”

 

Variables

All C# and JavaScript variables must start with a lowercase letter and each of the following words with a capital letter (camelCase)

var = mySpecialVariable

NEVER use shortened variable names like sel, opt, i etc. There are no optimization gains when doing this in frontend programming, and we want code which can be read by both computers and humans.

Methods/Functions and classes

 

Each word must start with a capital letter (PascalCase).

DoThisNow()

This makes it easy to distinguish methods, functions and classes from variables.

CSS class names

We use BEM + prefixes for CSS – no camelCase, no capital letters.

 

Please see the chapter on CSS for more about BEM.

Templates & files

Each word must start with a capital letter (PascalCase).

ProductList.cshtml

This is the most widely used naming convention in Dynamicweb.

Following these rules makes your code easier to read and collaborate on – whether tomorrow or a year down the line.

While there are several possible ways to work with translations in Dynamicweb, it is very important that you follow the conventions outlined below.

This will help you keep your code consistent, readable and maintainable.

  • The default language should always be English – no other languages are allowed in templates
  • Translation keys must be the word or sentence you want to translate:
    • Don´t @Translate("productlist_AddToCart”, “Add to cart”)
    • Do @Translate("Add to cart”, “Add to cart”)
  • Never include special characters at the end of your translation:
    • Don´t @Translate("User creation is complete.”, “User creation is complete.”)
    • Do @Translate("User creation is complete”, “User creation is complete”)
  • If you do not know how to translate a word or a sentence, please consult someone who does
  • Don’t translate directly from one language to another – a translation must make sense in both languages:
    • Don’t go from støvsuger to dust-sucker
    • Do go from støvsuger to vacuum cleaner

We recommend that you use either Chrome or Firefox while implementing, as they are both fairly stable. Chrome seems to be a lot faster when working in the DW9 Backend, so that is currently our preferred browser.

Here are some tips which will make your life easier and your projects more successful.

The default language in the Dynamicweb backend comes from the one that is set in the browser.

  1. In Chrome go to “Settings -> Show advanced settings -> Language and input settings”
  2. Remove extra languages except English and use that as default

Right click anywhere on the page and choose “Inspect element”.

  • Click the little “Inspect element” icon at the left corner of developer tools to quickly inspect elements.
  • The little icon after “Inspect element” gives you the possibility to quick test the responsiveness of your page.
  • Disable cache in the developer tools settings
  • In developer tools settings you may choose theme = Dark, to make it better for the eye
  • While the developer tools is open you may right-click on the page refresh button, to hard refresh the page while hard cleaning the cache.

The only thing you need is a Mac with Safari and an iPad or an iPhone connected to the computer.

  • On the iDevice go to Settings -> Safari -> Advanced and enable “Code inspector”
  • In the Safari browser on your Mac, do the same.
  • While the device is connected you only need to choose Developer in the top and then choose the connected device.