Skip to content

Latest commit

 

History

History
118 lines (79 loc) · 5.58 KB

guidelines.md

File metadata and controls

118 lines (79 loc) · 5.58 KB

Development Conventions and Guidelines

To keep the UI5 code readable and maintainable, please follow these rules, even if you find them violated somewhere. Note that this list is not complete. When a file is consistently not following these rules and adhering to the rules would make the code worse, follow the local style.

Table of Contents

General

  • Always consider the developers who USE your code! Do not surprise them, but give them what they expect. And make it simple.
  • Adhere to any local standard in the file
  • Use Unix line endings (LF-only)
  • There is no 80-character line length guideline, but that doesn't mean to abuse it.
  • Use comments. Don't rephrase the code, but tell the reader what is NOT in the code. Describe why your code does what it does. Prefer line comments.

JavaScript Coding Guidelines

  • No global JavaScript variables;
    • This also means: no undeclared variables
  • Do not access internal (private) members of other objects
  • Do not use console.log()

Code Formatting

  • Our ESLint and JSHint checks needs to run successfully; Check the ".eslintrc" and ".jshintrc" files for more information:
  • The WebStorm default settings for the JavaScript editor are pretty fine, but make sure space are used for indentation

Naming Conventions

  • Class names should use CamelCase, starting with an uppercase letter

Documentation (JSDoc)

For documenting JavaScript, UI5 Inspector uses the JSDoc3. See the JSDoc3 Toolkit Homepage for an explanation of the available tags. The JSDoc3 is checked from the ESLint and it is a mandatory.

Product Standards / Acceptance Criteria

UI5 Inspector needs to fulfill certain "product standards". While these are not directly related to code conventions, the most important ones are mentioned here, because new code needs to fulfill these requirements:

General:

  • Security (e.g. output encoding against XSS attacks)
  • Performance (not a yes/no question, but needs to be in focus)
  • Automated tests
  • Make sure other Open Source libraries (or parts of them) are officially approved before adding them to UI5 Inspector. Do not add code you "found" somewhere.

File Names and Encoding

Some of the target platforms of UI5 Inspector impose technical restrictions on the naming or structure of resources (files). Hence, these restrictions apply:

  • Folder names must not contain spaces
  • Single folder names must not be longer than 40 characters
  • Two resource names must not only differ in case
  • Avoid non-ASCII characters in resource names

Git Guidelines

Set the Git core.autocrlf configuration property to "false" (and make sure to use Unix-style linebreaks (LF-only))

The commit message consists of two or three parts, separated by empty lines:

  1. The commit summary (the first line)
  2. An optional commit description text (may contain additional empty lines)
  3. A data section

  • The summary line must be prefixed by [FIX] or [FEATURE] and should start with the control/component which was the main subject of the change

  • Instead of [FIX]/[FEATURE] and at any other location in the commit message [INTERNAL] can be used for commits/explanations which are not supposed to be part of the release notes because they are not relevant for users of UI5 Inspector

  • The data section consists of name-value pairs

    • Fixes https://github.com/SAP/openui5/issues/(issueNumber) when the change fixes a GitHub-reported bug; it is important that there is NO colon between "Fixes" and the URL!
    • Closes https://github.com/SAP/openui5/pull/(pullRequestNumber) when the change comes from a pull request; it is important that there is NO colon between "Fixes" and the URL! As the pull request number is not known before it is created, this is usually added by the UI5 Inspector committer handling the pull request
    • Further internal information - like CSS (for old SAP-internally reported bugs), BCP (for customer messages reported at SAP and new internal bug reports), a mandatory Change-Id, and the CR-Id ("Change Request ID", mandatory for maintenance codelines) - is added by SAP developers when required

  • A commit message can thus look like this:

    fix: prevent rerendering if the same model is set.

Fixes #123

Tools

  • It is helpful to configure your JavaScript editor to display whitespace and linebreak characters; this makes issues with mixed tabs/spaces and windows-style linebreaks immediately obvious
  • It also helps to configure the code formatter of your code editor accordingly. The default formatter for JavaScript in WebStorm is already pretty ok.

ESLint

UI5 Inspector comes with a ruleset for ESLint. Adhering to these rules is mandatory.

JSHint

UI5 Inspector comes with a ruleset for JSHint. Adhering to these rules is mandatory.