CONVENTIONS.md

   1 # Conventions
   2
   3 ### Directives
   4
   5 * **SHALL** is used to express mandatory requirements. (negative form: **SHALL NOT**)
   6   * Do not use MUST as an alternative to SHALL.
   7 * **SHOULD** is used to express recommendations. (negative form: **SHOULD NOT**)
   8 * **MAY** is used to express permissions .  (negative form: **NEED NOT**)
   9   * do not use CAN as an alternative to MAY.
  10
  11 ---------
  12
  13 ## Naming
  14
  15 - If a corresponding class or a similar concept exists in v8, name it with a postfix, `Wrap`.
  16 The following table shows how a v8 class and its matching lwnode class are named.
  17
  18 | v8      | lwnode      |
  19 |---------|-------------|
  20 | Context | ContextWrap |
  21 | Isolate | IsolateWrap |
  22
  23
  24 - If there is a corresponding functions in v8, it **SHALL** use the exact name.
  25 ```
  26   ContextWrap::Enter (lwnode)
  27   Context::Enter (v8)
  28 ```
  29
  30 - If not, it **SHALL** use the name starting with a small letter.
  31 ```
  32   IsolateWrap::pushHandleScope (lwnode internal)
  33 ```
  34
  35 - It **SHOULD NOT** use a brand name (e.g lwnode) to name apis. Because the brand name could be changed in future.
  36
  37 - The postfix, `Ref`, stands for `Reference`. Thus, it **SHOULD NOT** use it as a pointer `Ref*`.
  38
  39 ```diff
  40 - typedef Escargot::ContextRef* JsContextRef; // (x)
  41 ```
  42
  43 * EscargotShim works as a bridge between V8 and Escargot. It is responsible for
  44   transforming a V8 value to an Escargot value, and vice versa. This results in
  45   three types of "modules" as described by the following diagram.
  46
  47 ```
  48 +----+      +--------------+      +----------+
  49 | V8 |------| EscargotShim |------| Escargot |
  50 +----+      +--------------+      +----------+
  51 ```
  52
  53   * We deal with a three sets of APIs, it is often confusing which value, out of three,
  54     a variable refers to. To prevent this, we add a prefix when a variable is named as described below:
  55
  56 | API          | Prefix                                  |
  57 |--------------|-----------------------------------------|
  58 | V8           | v8 (can be omitted if context is clear) |
  59 | EscargotShim | lw                                      |
  60 | Escargot     | es                                      |
  61
  62 * This naming rules **SHALL** be applied to all ``api-*.cc`` files.
  63
  64 * Within EscargotShim, `ValueWrap` **SHALL** be used for type convertion between v8 and lwnode apis.
  65
  66
  67 ## Type conversion between lwnode world and v8 world
  68
  69 `api.cc` is like a middle land. Any value moving out from lwnode world **SHALL** be wrapped using `ValueWrap`.
  70
  71
  72
  73 ### New
  74 - Wrap any value using `ValueWrap` before returning it.
  75
  76 ```c++
  77 // Escargot::ValueRef* inherited
  78 auto esString = StringRef::createFromUTF8(...);
  79 auto lwValue = ValueWrap::createValue(string);
  80 // auto value = new ValueWrap(string); // deprecated
  81
  82 // Others
  83 // e.g) Escargot::Script
  84 auto lwValue = ValueWrap::createScript(...);
  85 ```
  86
  87
  88
  89 ### Use
  90
  91 - Wrap any value using `ValueWrap` before use it.
  92
  93 ```c++
  94 #define VAL(that) reinterpret_cast<ValueWrap*>(that)
  95 #define CVAL(that) reinterpret_cast<const ValueWrap*>(that)
  96
  97 // Usage:
  98 VAL(this); // = ValueWrap(reinterpret_cast<ValueWrap*>(this));
  99
 100 // e.g) use ValueRef* from `Local<String> name`
 101 VAL(*name)->value()->asString();
 102
 103 // e.g) use StringRef* from `Local<String> source_string of Source*`
 104 VAL(*source->source_string)->value()->asString();
 105
 106 // e.g) access ContextWrap::Enter();
 107 VAL(this)->context()->Enter();
 108 ```
 109
 110 ### Return
 111
 112 * Retrun a `ValueWrap` using a `Local`
 113
 114 ```c++
 115 auto esString = StringRef::createFromUTF8(...);
 116
 117 return Utils::NewLocal<String>(isolate, esString);
 118 ```
 119
 120 ### Exception Handling
 121
 122 * `IsolateWrap::IsExecutionTerminating` returns true if a pending exception that should be thrown exists.
 123 * Scheduling throwing an excpetion can be set through `IsolateWrap::scheduleThrow`.
 124 * If a javascript operation could make an exception (e.g `v8::Object::SetPrototype`), it should do exception handling.
 125
 126
 127
 128 # Language styles
 129
 130 - Type Names
 131   - Type names start with a capital letter and have a capital letter for each new word: `MyClass`, `MyEnum`.
 132 - Variable Names
 133   - Class data member
 134     - ``myValue_`` for a member variable
 135     - ``g_myValue`` for a global variable
 136     - ``s_myValue`` for a static variable
 137     - ``kMyConstValue`` for a (global) constant value
 138   - Common data (TBD)
 139     - 1) stringValue
 140     - 2) string_value (v8)
 141 - File Names
 142   - Filenames should be all lowercase and may include dashes (-).