From aaef93c5ca43d0b0204824306d0ac414e3e78f0c Mon Sep 17 00:00:00 2001 From: Sean Nguyen Date: Sun, 14 Dec 2025 22:43:57 +0000 Subject: [PATCH 1/2] feat: updates style guide markdown Updates the STYLE_GUIDE.md to include industry standards and best practices for TypeScript naming conventions, commenting, and imports. --- STYLE_GUIDE.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 71f716b..251c5bc 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -66,6 +66,59 @@ npx prettier . --check - Use function declarations - not arrow functions +### TypeScript Naming Conventions + +- Use **camelCase** (e.g. firstName, lastName) for variables and functions +- Use **UPPER_CASE** (e.g. FIRST_NAME, LAST_NAME) with underscores between words for constants/globals +- Use **PascalCase** (e.g. FirstName, LastName) for class, interface, enum, and type names + +### Variables + +- Use the `const` keyword for constant variables +- Use the `let` keyword for local variables. `let` has scoping restrictions, `var`, does not. +- Do NOT use the `var` keyword for variables +- Use meaningful variable names. Better to have longer, useful names than shorter, confusing ones. +- Do not use a variable if it will only be used once. +- Booleans: don't use negative names for boolean variables (BAD: `const isNotEnabled = true`, GOOD: `const isEnabled = true`) + +### Commenting + +#### When to add Comments + +- Include comments for intricate or non-obvious code segments +- Clarify how your code handles edge cases or exceptional scenarios +- Document workarounds due to limitations or external dependencies +- Mark areas where improvements or additional features are needed. Link to GitHub Issue, if possible. + +#### When NOT to add Comments + +- Avoid redundant comments that merely repeat what the code already expresses clearly. +- If the code’s purpose is evident (e.g., simple variable assignments), skip unnecessary comments. +- Remove temporary comments used for debugging once the issue is resolved. +- Incorrect comments can mislead other developers, so ensure accuracy. + +### Organize Imports + +- With clean and easy to read import statements you can quickly see the dependencies of current code. Make sure you apply following good practices for import statements. +- Unused imports should be removed. +- Groups of imports are delineated by one blank line before and after. + +### Use TypeScript Aliases + +This will avoid long relative paths when doing imports. + +Bad: + +``` +import { UserService } from '../../../services/UserService'; +``` + +Good: + +``` +import { UserService } from '@services/UserService'; +``` + ## Pull Request Instructions - Set base branch to "develop" @@ -102,3 +155,7 @@ npx prettier . --check - **Run tests frequently** during development - **Use hot reloading** for fast feedback - **Implement CI/CD** for automated testing + +``` + +``` From 13b3d2cc0d5d50409c61d88491aa6c48a3a7dbca Mon Sep 17 00:00:00 2001 From: Sean Nguyen Date: Sat, 3 Jan 2026 12:47:30 -0800 Subject: [PATCH 2/2] feat: updates style guide, addressing PR comments Adds file naming, TODO commenting, writing queries, writing tests, and PR details to style guide. --- STYLE_GUIDE.md | 85 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 10 deletions(-) diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 251c5bc..3148571 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -66,11 +66,13 @@ npx prettier . --check - Use function declarations - not arrow functions -### TypeScript Naming Conventions +### Naming Conventions -- Use **camelCase** (e.g. firstName, lastName) for variables and functions +- Use **camelCase** (e.g. firstName, lastName) for variables, functions, class members, and type members. - Use **UPPER_CASE** (e.g. FIRST_NAME, LAST_NAME) with underscores between words for constants/globals -- Use **PascalCase** (e.g. FirstName, LastName) for class, interface, enum, and type names +- Use **PascalCase** (e.g. FirstName, LastName) for class, interface, enum, and type names; enum members should also be in PascalCase; exported components should also be in PascalCase. +- Boolean variables should be prefixed with a verb (e.g. isEnabled) +- Use **camelCase** for file names _unless_ the file exports a component, in which case use **PascalCase** ### Variables @@ -97,7 +99,69 @@ npx prettier . --check - Remove temporary comments used for debugging once the issue is resolved. - Incorrect comments can mislead other developers, so ensure accuracy. -### Organize Imports +#### TODO Comments + +In general, TODO comments are a big risk. We may see something that we want to do later so we drop a quick `// TODO: Replace this method` thinking we'll come back to it but never do. + +If you're going to write a TODO comment, **link to the GitHub Issues board**. + +There are valid use cases for a TODO comment. For example, you may be working on a big feature and you want to make a pull request that only fixes part of it. Or, you may want to call out some refactoring that still needs to be done, but that you'll fix in another PR. + +``` +// TODO: Refactor this class. Issue #123 +``` + +This is actionable because it forces us to go to our issue tracker and create a ticket. That is less likely to get lost. + +### Writing Tests + +See the test templates for writing tests in `/docs/examples/` + +- [GraphQL Template](https://github.com/hack4impact/operations-api/blob/main/docs/examples/graphql-examples.md) +- [REST Template](https://github.com/hack4impact/operations-api/blob/main/docs/examples/rest-examples.md) + +### Writing Queries + +#### Filtering/Sorting + +Use the following structure for writing queries with filters and sorts. Note: you **MUST** name the variables **"filter"** and **"sort"**, nothing else. + +Example query using filter and sort: + +``` +query { + volunteers( + filter: { + statuses: ["PROFESSIONAL", "STUDENT"], + roles: ["Developer"], + chapters: ["Cal high"] + }, + sort: { + firstName: ascending + } + ) { + volunteer_id + first_name + } +} +``` + +### Code Organization + +#### General Structure + +Our code should follow the structure below, from top to bottom: + +1. Imports are first at the top of the file. Only include used imports, and they should be grouped appropriately (see _Organize Imports_ for more). +2. Constant variable declarations should follow after the imports and before any class definitions. +3. Type declarations follow constants (e.g. `type CreateChatperInputs`). +4. Enum declarations. +5. Interface definitions should be next (e.g. `NonprofitsQueryArgs`). +6. Core logic/component definition should be next (e.g. `export const className`). This includes the core class, function, component that the file primarily exports. +7. Helper functions/methods. Define event handlers, utility functions, or methods used internally by the main logic. +8. Export should be last. Explicitly export the primary functionality along with additional exports at the bottom. + +#### Organize Imports - With clean and easy to read import statements you can quickly see the dependencies of current code. Make sure you apply following good practices for import statements. - Unused imports should be removed. @@ -122,9 +186,14 @@ import { UserService } from '@services/UserService'; ## Pull Request Instructions - Set base branch to "develop" -- Add screenshots of results +- Follow the PR template +- Link your issue so it the first line reads "Closes #{ISSUE NUMBER}" (replace curly braces with number) +- Describe your changes and the ticket in the **"Overview"** section +- Describe what testing you completed to verify the feature (manual/unit testing) in the **"Testing"** section +- Add screenshots of results in the **"Screenshots"** section +- Complete the checklist by replacing the "[ ]" with "[x]" (or simply checking the boxes after publishing the PR) +- Add any additional notes at the bottom in the **"Notes"** section - Assign at least 2 reviewers -- Link your issue (follow the PR template) ### Best Practices to Write REST API @@ -155,7 +224,3 @@ import { UserService } from '@services/UserService'; - **Run tests frequently** during development - **Use hot reloading** for fast feedback - **Implement CI/CD** for automated testing - -``` - -```