Development Priorities - dsriseah/ursys GitHub Wiki

This document describes the philosophy behind the design of URSYS to support a particular target audience of developers.

URSYS is a build framework for web applications of medium complexity and speed, primarily used by people for whom programming is not their main job. Our target developers tend to be teachers, researchers, designers, and experimenters who do not have a support team CI/CD, separate quality assurance, or release management.

We also try to accommodate developers who are not interested in the deep guts of computer programming theory by relying on simple data structures and concepts that map well to "one program" rather than a constellation of servers and services to manage.

The developer experience goal is to provide immediate gratification and feedback in the development cycle:

• "I can clone the source code from git, do a one-line install, and it runs immediately without other setup".
• "I can modify the source code as the program runs results in instant feedback"
• "I can understand data structures and infer how the program works without 10 years of programming experience or a CS degree"

These directives list metrics that match our developer experience goals.

• Projects are standalone, one-command install and startup without additional configuration needed to “just see something happen” immediately.
• Projects can be built on a Macbook with our minimum installation requirements (xcodeselect to add git and nvm to provide node version control)
• No need to install external servers (e.g. using a self-contained database like sqlite or lokijs instead of mongodb) requiring any deep knowledge of the operating system, package managers, etc in the base tool; "Five minute installation" is the goal.
• Standardize on free tools and code editors to make installation quick and accessible for students and researchers, with standardized config of workspace via prettier, eslint, editorconfig, .gitignore, the vscode .code-workspace and .vscode/settings.json, and nvm.
• Use hot reloading servers wherever possible when any file is touched.

These directives are for providing a uniformly good editing experience for everyone who is touching the source code.

• We enforce source code formatting on save with the prettier configuration file and the VSCode Prettier extension.
• Linting is handled with our custom set of ESLint rules in the editor with the VSCode ESLint plugin.
• Use human-readable data formats in file-based configuration separate from source code
• Accessible folders and files that are in human readable formats for easy “copy and paste” archiving by academic users
• Generally use MIT-licensed libraries, and release under MIT license
• Configure all editors to live-format and flag errors at edit time so users see their mistakes immediately, emphasizing “live-reload” and “live-linting” tools in the code editor
• Enforce (or flag) use of the source code-workspace project file, so recommended VSCode extensions are installed by users
• Provide runtime status messages in the browser javascript

These directives are for maintaining clarity of the source code and program operation for people who are exploring parts of it for the first time.

• System features should be autoconfiguring on startup without need for explicit calls. If they are managing dynamic data, they maintain a collection of a guaranteed up-to-date data in their buffers. Importing a module of this type should handle its connections through the lifecycle interface.
• Leave breadcrumbs that refer to other necessary files or information so new users/researchers can find the relevant related areas, but we try to avoid having too many indirect jumps.
• If multiple files are part of the same system or module, name them so they sort alphabetically together and be consistent with other patterns in the source code
• Add runtime error detection and helpful reporting as confusion and installation errors are noted in supporting the code
• Double-check for clear and consistent technical system naming, avoiding use of words that are overused like “type”, “module”, “feature”, etc as much as possible.

These directives fix coding style that ignores other developers' needs to understand the code and how it works.

• Study the Guide: Codestyle for our module format and required autoformatting support
• Don’t leave debug comments in the source code before making an official pull request
• Don’t leave testing stuff in the Javascript console
• Don’t leave flagged bugs in the code
• Don’t leave unused source code, functions, or API calls. Mark them as unused or deprecated in the function signature or first line of function
• Ensure the build process does not emit ANY warnings; resolve them immediately
• Follow module commenting style and naming conventions defined in .vscode/module.code-snippets
• Check your method names, variables, parameters, and API calls for grammatical and spelling consistency.
• Avoid "tricky code" that uses esoteric knowledge of the language that may be unclear to intermediate-level programmers
• Avoid premature optimization that makes . Optimize when performance becomes an issue.
• Avoid indirect access or multi-hop data lookups/invocations as much as possible. If you are passing the same operation or parameters more than once under different names, try to simplify it.

These directives address repo commits and documentation.

• Describe commits using a human-centered terms as to the effect of your change (providing context) and the technical justification for the change if it tricky or relevant.
• Bug reports should not make assumptions or armchair debug the problem, because they are misleading. Describe ONLY steps to reproduce the bug, then what you expected to happen, followed by what actually happened including a screenshot of what was seen. Because users have such different mental images of how the code works, guessing about the cause in a bug report is not generally helpful even when made by experienced programmers.