CityCatalyst Coding Standards

Coding Standards to Javascript

To ensure uniformity of our code base the following standards should be applied.

1. Indenting and Formatting:

• Choose an indentation style (e.g., 2 spaces or 4 spaces) and stick with it throughout the project.
• Use consistent line breaks and spacing for improved readability.

2. Naming Conventions:

• Follow consistent naming conventions for variables, functions, classes, and components.
• Use meaningful and descriptive names that convey the purpose and functionality of the code element.
• For TypeScript, consider using camelCase for variables and functions, and PascalCase for classes and components.

3. Type Annotations:

• Make full use of TypeScript's static type system to catch errors early.
• Always annotate function parameters and return types with appropriate type definitions.
• Use interfaces or type aliases for complex data structures.

4. Imports and Exports:

• Use explicit import and export statements for better clarity.
• Organize imports alphabetically and group them by external dependencies, internal modules, and relative imports.

5. Components and Containers:

• Separate your components into presentational (dumb) components and container (smart) components.
• Presentational components focus on rendering UI and receive data via props.
• Container components handle data logic and interact with Redux, state, or context.

6. State Management:

• If using Redux, structure your store with actions, reducers, and selectors.
• Use async actions and middleware for handling asynchronous operations.
• Consider using the Redux Toolkit to simplify store setup and reduce boilerplate.

7. File Structure:

• Organize your files and folders logically to promote easy navigation.
• Group related components, styles, and tests in the same directory.

8. Code Comments:

• Write clear and concise comments explaining complex logic, algorithms, or code decisions.
• Avoid unnecessary comments that simply repeat what the code is doing.

9. Testing:

• Write unit tests and integration tests for your components and functions.
• Use a testing library like Jest along with testing utilities like React Testing Library.

10. Linting and Formatting Tools:

• Use ESLint and Prettier to enforce coding standards and formatting rules.
• Configure them to automatically format code and catch potential issues.

11. Code Reviews:

• Conduct regular code reviews to ensure adherence to coding standards.
• Encourage team members to provide constructive feedback during reviews.

12. Documentation:

• Maintain a README file with project setup instructions, architecture overview, and any other necessary information.
• Document important decisions, libraries used, and any coding guidelines that may not be obvious.

Code Formatting tools

Prettier

Prettier is an opinionated code formatter with support for:

1. JavaScript (including experimental features)
2. JSX
3. TypeScript
4. CSS, Less, and SCSS
5. HTML
6. JSON
7. GraphQL
8. Markdown, including GFM and MDX v1
9. YAML,

We are using prettier to enable developers stick to the standard of code. They are two ways to use prettier:

Installing its as a dev dependancy

1. Run the install

npm install --save-dev --save-exact prettier

2. Create an empty config file in the root of you directory

echo {}> .prettierrc.json

3. Next, create a .prettierignore file to let the Prettier CLI and editors know which files to not format. Here’s an example:

# Ignore artifacts:
build
coverage
node_modules
.next

4. Running prettier

npx prettier . --write

5. If you have a CI setup, run the following as part of it to make sure that everyone runs Prettier. This avoids merge conflicts and other collaboration issues!

npx prettier . --check

6. Setting Rules - Here's and example of how you can set rules in .prettierrc file:

{
    "semi": true, // this tells the code editor to add semi-colons on save
    "overrides": [] // if there any overrides you can set them in here 
}

Installing the prettier extension

1. Search for prettier in vscode extensions tab
2. Once installed goto, Settings, type on prettier in the search bar, select Text Editor select prettier as the default formatter in the dropdown,
3. Search for formatonsave on the search bar enable it on the check mark.

Coding Standards to Python

To ensure uniformity of our code base the following standards should be applied (source)[https://peps.python.org/pep-0008/].

1. Indentation:

• Spaces are the preferred indentation method.
• Use 4 spaces per indentation level. It is optional for continuation lines.

2. Format:

• Close brace/bracket/parenthesis on multiline constructs may either line up under the first non-whitespace character of the last line of list.
• Limit all lines to a maximum of 79 characters (for docstrings/comments limit to 72).
• Break formulas before binary operations.
• Surround top-level function and class definitions with two blank lines.
• Method definitions inside a class are surrounded by a single blank line.
• Extra blank lines may be used (sparingly) to separate groups of related functions.
• Single-quote string and double-quoted strings are the same. Pick one and stick to it.
• Avoid trailing whitespace anywhere.

3. Imports:

• Imports should usually be on separate lines.
• Imports are always put at the top of the file.
• Following order: standard library imports, related third party imports, local application/library specific imports.
• Absolute imports are recommended.

4. Code Comments:

• Write clear and concise comments explaining complex logic, algorithms, or code decisions.
• Avoid unnecessary comments that simply repeat what the code is doing.
• The first word should be capitalized, unless it is an identifier that begins with a lower case latter.

Use inline comments sparingly, separated by at least two spaces from the statement.

5. Naming Conventions:

• Names that are visible to the user as public parts of the API should follow conventions that reflect usage rather than implementation.
• Follow consistent naming conventions for variables, functions and classes.
• Use meaningful and descriptive names that convey the purpose and functionality of the code element.
• Modules should have short, all-lowercase names.
• Class names should use the CapWords convention.
• Function and variable names should be lowercase, with words separated by underscores as necessary.
• Constants are written in all capital letters with underscores separating words.

10. Linting and Formatting Tools:

• Black code style is a PE 8 compliant opinionated formatter.

11. Code Reviews:

• Conduct regular code reviews to ensure adherence to coding standards.
• Encourage team members to provide constructive feedback during reviews.

12. Documentation:

• Document important decisions, libraries used, and any coding guidelines that may not be obvious.