CODE STANDARDS CHECKLIST (WIP)

[benloh]

Sri is codifying the past 7 years of our programming code style in one place so they can assign fancy numbers to them or something. Plus they keep seeing these issues pop up over and over, so this indicates that maybe they are not clearly stated.

GENERAL CONVERSIONS

• [ ] convert export function FName to export { FName } at the end of the module, so it's easier to see everything at the end
• [ ] for exports, ensure there is a short description and that they are exported in functional groups when it make sense. transpiler-v2 is an example of this
• [ ] Convert any relative references in import statements to the path alias style. The available path aliases (like 'modules' and 'script') are defined gem-srv.tsconfig.json
• [ ] use jsdoc /** API: description for any code that is an API method that's being exported. Everything else should use m_FunctionName syntax, and also be noted as /** support: desc
• [ ] Ensure that the left paragraph of a jsdoc comment aligns by using a TAB on the lines after the initial /** opener.
• [ ] Check that you have removed extraneous console.log output by setting the module's DBG flag or commenting them out.

BONUS: GENERAL CONVENTIONS

• [ ] module imports now use the import * as MODNAME from ..., not import { MethodA } from ...
• [ ] module exports should be in groups of related items with comments (see transpiler for example)
• [ ] module-scoped support functions are of the form function m_SupportMethodName ()
• [ ] module-scoped dictionaries and constants are of the form SOMETHING_DICT
• [ ] module-scoped variables are of the form m_variable_name
• [ ] function parameters are of the form function (aVar, bSomeOtherVar)
• [ ] function-scoped variables are of the form snake_case_var
• [ ] functions defined functions use form f_function_name or u_function_name (u stands for utility)

BONUS: STYLE CONVENTIONS LOOSELY KEPT

• [ ] functions that return a parameterized result are named GetTypeOfResult(param)
• [ ] functions that for return a singleton or unique system entity do not use Get as a prefix
• [ ] functions that perform an imperative action are named VerbTheThing()
• [ ] functions that returns a promise are named PromiseTypeOfResult
• [ ] functions exported from a module are PascalCase
• [ ] classes and functional constructors are PascalCase
• [ ] functions declared in a class are camelCase
• [ ] variables declared inside a function are snake_case
• [ ] parameters declared in a function are camelCase

WIP: DATA AND COMMAND ABSTRACTIONS

A module or class API is a collection of methods that are designed to communicate its conceptual model of use. In object-oriented terms, I think of this as figuring out:

• what is its identity+role in an overall operation as well as its scope of responsibility.
• what type of command & control structure is it designed for?
• how is command & control effected? lifecycle hook? reactive? imperative? asynchronous?
• what immediate systems does it report to, and how does that work with the type of C&C? push? hook? poll? call? callback?
• what immediate systems does it need to monitor to do its job, and how does that work with the type of C&C? push? hook? poll? call? callback?

Knowing that, you can then design the API so the following is clear and consistent, and that its scope of responsibility continues to be clear:

• a model for its self-managed operations and data transformations
• a model for what conditions it delivers reliable operation and data
• a model for how it is managed by other system entities
• a model for how it manages other entities to meet its responsibilities

This is all very abstract, so we need to come up with canonical STEP-related concepts and patterns that are already in use.

[benloh]

In GitLab by @daveseah on May 9, 2022, 14:23

comment from ben from slack re appcore to datacore connections (from a discussion on how a datacore API operates relative to something that uses it like an appcore)

I think there were three levels of constraints for datacore that are somewhat related:

• does not have other dependencies (e.g. others can load it without getting into circular dependencies)
• passive in the sense that it by itself does not initiate data loading…
• …but (and perhaps this is the clarification you’re addressing), once prompted, it can initiate its own data loading and saving for a range of data objects.

[benloh]

In GitLab by @daveseah on May 9, 2022, 15:23

Another area: Typescript Conventions

• When do we use t-name.d.ts and are we using it correctly? I think these are autoloader definitions but they aren't set up correctly in our toolchain so we import them directly.
• A t-name.d.ts is a map of all the related system concepts in one subsystem. For example, t-script.d.ts is everything related to the transpiler's scripting, and t-assets.d.ts is everything related to the asset management/asset loader operations.

We use a few prefixes in a general way that is from the typescript documentation but maybe not specific enough as we are with our variable and function naming.

• [ ] The T prefix is used for any general type declaration.
• [ ] The I prefix is used for general interface declarations, which are a substitute for "base classes" and "inheritance" in C++ like languages.
• [ ] The class SubsysObject declaration can use both T and I declarations, and is used to represent the object type.
• [ ] The TSubsys prefix is used to identify groups of related types. Example: TSMCProgram is a type for the transpiler+execution engine which runs our ad-hoc "Stack Machine Code"
• [ ] The E prefix is used for any enum declarations

There are some special cases:

• [ ] TPrefix are used for parameters. IPrefix (interfaces) can do something similar but are only for classes that implement them.
• [ ] class SubsysObject implements IPrefix gives you the choice of defining properties/methods on either IPrefix or SubsysObject. In general though you should use the class declaration itself when you mean the object, and the interface for when you are expecting some base class operations ONLY.

Typescript Tricks worth noting:

• enums are accessed like EBundleType.BLUEPRINT
• declare enum MyEnum { A, B, C }
• type consisting of the declared element of an enum: type enumValues = keyof typeof MyEnum
• type of object that uses enum as its keys: type ObjectWithKeysOfEnumAsKeys = { [key in enumValues]: string }
• runtime check of enum keys: Object.values(EBundleType).includes('blueprints) which works because typescript converts EBundleType into an object.
• to declare a parameter must be in enum: symbolType: keyof TSymbolData
• string template types look like TAssetType = 'sprites' | 'sounds' | 'projects', and you can specify this similarly as { [K in TAssetType]:any } which restricts the properties to the possible type values only
• when you need to infer the type of a runtime object: type enumValues = keyof typeof MyEnum (see keyof vs keyof typeof)

[benloh]

In GitLab by @daveseah on Jun 8, 2022, 08:00

Yet another area: React Handler (and UI handlers in general)

An issue I see is that there is no distinction made between what is a user interface event handler (aka code that routes an Event object) versus application logic (code directly receives data to perform some application operation) versus gui logic (code that directly receives an event or data to change the state of the gui without changing any application data). These are three distinct operations, and our code should show this distinction.

EXAMPLE TO UNPACK (WIP)

Example below is the fragment of code to discuss

SlotEditor functional (not class!) component

<button type="button" onClick={SaveSlot}>

function SaveSlot(e) {
  WIZCORE.SaveSlotLineScript(e);
}

WIZCORE module

export function SaveSlotLineScript(e) {
  const {
    slots_linescript,
    script_tokens,
    sel_linenum
  } = STORE.State();
  const lineIdx = CHECK.OffsetLineNum(sel_linenum, 'sub'); // 1-based
  script_tokens.splice(lineIdx, 1, slots_linescript);
  STORE.SendState({ script_tokens });
}

quick notes:

1. onClick prop is binding to another function definition and not explicitly passing the event. It's important to show that the event is being passed because this makes it clearer that it's a UI event handler. Better written as onClick={event=>SaveSlot(event)} even though it is more verbose. This also has the effect of (1) binding the containing variable scope to the arrow function explicitly, which is helpful in class components that are not using .bind() explicitly and (2) you can tack on additional parameters other than just event to reuse the same handler but with different parameters.

2. function SaveSlot(e) is not doing very much other than redirecting to another call. It's not even unpacking data from the event (which is also unidentified). It's just code noise and it's passing UIEvent to WIZCORE directly to perform a data operation. This is conflating two concerns into one.

3. export function SaveSlotLineScript(e) in WIZCORE doesn't even use the event that's passed (and it's still called e and untyped). It's performing a pure data operation based on internal state.

quick outline:

• provide examples of a clean separation of concerns
• how to handle different kinds of UI operations with different architectural strategies?