Open Web App Coding Conventions - Update

Tags: #<Tag:0x00007f3033b8b658>

Hello! I am part of a team working on documentation updates, namely to the developer GitBook documentation. We are updating the Creat Your Module to use Open Web Apps instead, and part of what we want is to add in some conventions. I noticed this thread about these conventions, however, there was no link to the outcome. If you know what the conventions are, or where they are located that would be great so we could add them. If there is no such documentation, then this would be a great chance to discuss it! Namely, we’re looking for documentation on:

JavaScript

  • Style
  • Should we use the most recent version (ES6), and documentation on its important features
  • What should be JavaScript, and what should be CSS (when overlap exists)

CSS

  • What should be module CSS and what should be and update to the UI Commons
  • ID naming conventions
  • Class naming conventions
  • Use of @media
  • Use of transitions, after, before, ect.
  • Use of layouts (Floats & clearfix or Flexbox or …)

HTML

  • What elements should be used when
  • Location of script & style elements, even if loaded by fragments
  • Do we want to use noscript tags too?

Libraries

  • Which libraries are fine to use (JQuery, …)
  • How to include them (a file or through script tags)

Fragments

  • How to load them
  • Making a fragment
  • Fragment Conventions

Please understand that we only have a limited amount of time to work on this documentation before we’ll have to cut it off and submit it, at which time someone else can continue on it. Thusly, perhaps it would be not only useful to provide a suggestion for the conventions, but also explain which conventions we should prioritize.

Hi,

I am very excited to see the documentation :slight_smile:.

Further, I have already created a topic to discuss regarding this one, you can find some points from this following thread also,


JavaScript

  • Style
  • Should we use the most recent version (ES6), and documentation on its important features
  • What should be JavaScript, and what should be CSS (when overlap exists)

Here, you can include these following aspects also,

  • Common logging method for the OWA. You can get more from here, Logging for the Open Web App Development
  • variable names and method names declaration conventions
  • Double quote and single quote usages for the good practice

These are some useful links to get more conventions for JS good practices. You can pick some interesting points from here also,

  1. https://modernweb.com/45-useful-javascript-tips-tricks-and-best-practices/
  2. https://blog.risingstack.com/javascript-clean-coding-best-practices-node-js-at-scale/

@suthagar23

Hey,

I had already looked at that thread, and the thread seemed to have ended before most of the information was revealed. The only like I found profitable to look for conventions was the Concepts Dictionary OWA, however, upon reaching the page it has a failing build, so I’m unsure if that is still true. I would appreciate if you have any more direct posts or links that were part of that thread’s discussion, but were not posted.

As for the logger, it appears simple enough. I would like to know of how high a priority this should be in the documentation however.

The first link provided did have some fine conventions, however, they were for ES5, not ES6 so some of them are oudated :man_shrugging: . The second link was updated for ES6, and we actually already had a lot of that already documented. As for the parts in these two articles that weren’t documented, I would count this as being low priority as most of them were not conventions or tricks inherent to JavaScript, but rather conventions and tricks in programming languages in general.

If there are any other conventions or tips about other things that aren’t JavaScript that you know about, or have suggestions about, I’d love to know!