mirror of
https://github.com/exogen/t2-mapper.git
synced 2026-01-19 20:25:01 +00:00
68 lines
4.3 KiB
Markdown
68 lines
4.3 KiB
Markdown
- Keep track of what your current working directory is, and consider it when
|
|
running shell commands. Running a command in a directory you didn't expect can
|
|
potentially be catastrophic. Always use the correct relative paths to files
|
|
based on the current directory you are in.
|
|
- Some scripts may expect the current working directory of the process to be
|
|
a specific path. For example, most scripts in the `scripts` folder expect to
|
|
be run from the root of the repository, so file and directory paths are
|
|
relative to that.
|
|
- Always write new scripts in TypeScript. Use ES6 import and export, never
|
|
`require()` or `createRequire()`.
|
|
- If you think you need to use `require()` to get something working, try
|
|
changing how you are importing it instead (like importing the default export,
|
|
`import * as ...`, or other strategies).
|
|
- Despite preferring TypeScript, it's OK if some code generation tools output
|
|
.js, .cjs, or .mjs files. For example, Peggy (formerly PEG.js) generated
|
|
parsers are JavaScript. Likewise with .js files that were generated by the
|
|
TorqueScript transpiler.
|
|
- TypeScript can be executed using `tsx`.
|
|
- Don't commit to git (or change any git history) unless requested. I will
|
|
review your changes and decide when (and whether) to commit.
|
|
- Import Node built-in modules using the `node:` prefix.
|
|
- Use Promise-based APIs when available. For example, prefer using
|
|
`node:fs/promises` over `node:fs`.
|
|
- For `node:fs` and `node:path`, prefer importing the whole module rather than
|
|
individual functions, since they contain a lot of exports with short names.
|
|
It often looks nicer to refer to them in code like `fs.readFile`, `path.join`,
|
|
and so on.
|
|
- Format code according to my Prettier settings. If there is no Prettier config
|
|
defined, use Prettier's default settings. After any code additions or changes,
|
|
running Prettier on the code should not produce any changes. Instead of
|
|
memorizing how to format code correctly, you may run Prettier itself as a tool
|
|
to do formatting for you.
|
|
- The TorqueScript grammar written in Peggy (formerly PEG.js) can be rebuilt
|
|
by running `npm run build:parser`.
|
|
- Typechecking can be done with `npm run typecheck`.
|
|
- Game files and .vl2 contents (like .mis, .cs, shapes like .dif and .dts,
|
|
textures like .png and .ifl, and more) can all be found in the `docs/base`
|
|
folder relative to the repository root.
|
|
- You are most likely running on a macOS system, therefore some command line
|
|
tools (like `awk` and others) may NOT be POSIX compliant. Before executing any
|
|
commands for the first time, determine what type of system you are on and what
|
|
type of shell you are executing within. This will prevent failures due to
|
|
incorrect shell syntax, arguments, or other assumptions.
|
|
- Do not write excessive comments, and prefer being concise when writing JSDoc
|
|
style comments. Assume your code will be read by a competent programmer and
|
|
don't over-explain. Prefer excluding `@param` and `@returns` from JSDoc
|
|
comments, as TypeScript type annotations and parameter names are often
|
|
sufficient - let the function names, class names, argument/parameter names,
|
|
and types do much of the talking. Prefer only writing the description and
|
|
occasional `@example` blocks in JSDoc comments (and only include examples if
|
|
the usage is somewhat complex).
|
|
- JSDoc comments are more likely to be needed as documentation for the public
|
|
API of the codebase. This is useful for people reading docs (which may be
|
|
extracted from the JSDoc comments) or importing the code (if their IDE
|
|
shows the JSDoc description). You should therefore prioritize writing JSDoc
|
|
comments for exports (as opposed to internal helpers).
|
|
- When in doubt, use the already existing code to gauge the number of comments
|
|
to write and their level of detail.
|
|
- As for single-line and inline comments, only write them around code if it's
|
|
tricky and non-obvious, to clarify the motivation for doing something.
|
|
- Don't write long Markdown (.md) files documenting your plans unless requested.
|
|
It is much better to have documentation of the system in its final state
|
|
rather than every detail of your planning.
|
|
- Do not make any assumptions about how TorqueScript works, as it has some
|
|
uncommon syntax and semantics. Instead, reference documentation on the web, or
|
|
the code for the Torque3D SDK, which contains the official grammar and source
|
|
code.
|