Skip to content

feat: updates styleguide markdown #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
seanmnguyen wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

feat: updates styleguide markdown #78

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aaef93c
feat: updates style guide markdown
seanmnguyen Dec 14, 2025
0d145e6
Merge branch 'develop' into feature/76-add-styleguide-markdown
soramicha Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions STYLE_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,59 @@ npx prettier . --check

- Use function declarations - not arrow functions
Copy link
Collaborator

@soramicha soramicha Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you add a file naming convention as well?

Copy link
Collaborator

@soramicha soramicha Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and specify for which types of files we would name in what certain way


### 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
Copy link
Collaborator

@soramicha soramicha Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add more details on what a PR should include? Basically reiterating the PR template that's shown whenever we make a PR, and what additional things or examples we can write in it.


- Set base branch to "develop"
Expand Down Expand Up @@ -102,3 +155,7 @@ npx prettier . --check
- **Run tests frequently** during development
- **Use hot reloading** for fast feedback
- **Implement CI/CD** for automated testing

```
Copy link
Collaborator

@soramicha soramicha Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are some other parts that would be great if you can add:

  • standard patterns of writing tests (basically I want all of our way of writing tests to be consistent)
  • standard patterns of writing certain code (such as filtering/sorting - right now, we are all writing them in our own way and it would be difficult to use them if they are all each uniquely structured) for now, mainly writing rules for this is the goal - in the future, we would need to add more when it comes to creating components and such but it's not necessary at the moment.

like for filtering, i think this way looks good: #69

and so on Postman, we would call like this:

image

And so it would be ideal to have filter AND sorting to be structured something like this:

query {
volunteers(
filter: {
statuses: ["PROFESSIONAL", "STUDENT"],
roles: ["Developer"],
chapters: ["Cal high"]
}
sort: {
firstName: ascending
}
) {
volunteer_id
first_name
}
}

something like that so variables "sort" and "filter" are the same and not renamed to something like "sortingOrder", etc.


Copy link
Collaborator

@soramicha soramicha Dec 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you also add a section of code organization? so in a file, in what order would we put our code? for example, imports are up first obviously, then we would add what? if we had variables, etc. would we put them at the very top first before the rest of our code, etc.

this is to ensure that whenever we access files, we can quickly scan for places we want to know if our code organization is consistent, which would save us time

```