# Zirkol App Style Guide
> To keep strong consistency, please follow this style guide during naming, declaring and styling
[TOC]
## Variable and Function
- Use `camelCase` for variable and function names
> Reason: Conventional JavaScript
### Bad example
```ts
var FooVar;
function BarFunc() { }
```
### Good example
```
var fooVar; //Btw, use let instead of var
function barFunc() { }
```
## Class
- Use `PascalCase` for class names:
> Reason: This is actually fairly conventional in standard JavaScript.
### Bad example
```ts
class foo {}
```
### Good example
```ts
class Foo {}
```
- Use `camelCase` of class members and methods
> Reason: Naturally follows from variable and function naming convention.
### Bad example
```ts
class Foo {
Bar: number;
Baz() { }
}
```
### Good example
```
class Foo {
bar: number;
baz() { }
}
```
## Interface, Type, Namespace
- Use `PascalCase` for name
> Reason: Similar to class, and namespace convention followed by the TypeScript team. Namespaces are effectively just a class with static members. Class names are PascalCase => Namespace names are PascalCase
- **Don't** prefix with `I`
> Reason: Unconventional. lib.d.ts defines important interfaces without an I (e.g. Window, Document etc).
- Use `camelCase` for members
> Reason: Similar to class
### Bad example
```ts
interface IFoo {
}
```
### Good example
```ts
interface Foo {
}
```
## Enum
- Use `PascalCase` for enum names
> Reason: Similar to Class. Is a Type
- Use `PascalCase` for enum member
> Reason: Convention followed by TypeScript team i.e. the language creators e.g SyntaxKind.StringLiteral. Also helps with translation (code generation) of other languages into TypeScript.
### Bad example
```ts
enum color {
red
}
```
### Good example
```ts
enum Color {
Red
}
```
## `Null` vs `Undefined`
- Prefer not to use either for explicit unavailablity, define a `Optional Type` instead.
> Reason: these values are commonly used to keep a consistent structure between values. In TypeScript you use types to denote the structure
### Bad example
```ts
let foo = { x: 123, y: undefined };
```
### Good example
```ts
let foo: { x: number, y?: number } = { x:123 };
```
- Use `undefined` in general (do consider returning an object like `{ valid: boolean, value?: Foo }` instead)
### Bad example
```ts
return null;
```
### Good example
```ts
return undefined;
```
- Use `null` where it's a part of the API or conventional
> Reason: It is conventional in `Node.js` e.g. `error` is `null` for NodeBack style callbacks.
### Bad example
```
cb(undefined)
```
### Good example
```
cb(null)
```
- Use truthy check for `objects` being null or undefined
### Bad example
```ts
if (error === null)
```
### Good example
```ts
if (error)
```
- Use `== null` / `!= null` (not `===` / `!==`) to check for `null` / `undefined` on primitives as it works for both `null`/`undefined` but not other falsy values (like `''`, `0`, `false`) e.g.
### Bad example
```ts
if (error !== null) // does not rule out undefined
```
### Good example
```ts
if (error != null) // rules out both null and undefined
```
## Quotes
- Prefer single quotes (') unless escaping.
> Reason: More JavaScript teams do this (e.g. airbnb, standard, npm, node, google/angular, facebook/react). It's easier to type (no shift needed on most keyboards). Prettier team recommends single quotes as well Double quotes are not without merit: Allows easier copy paste of objects into JSON. Allows people to use other languages to work without changing their quote character. Allows you to use apostrophes e.g. He's not going.. But I'd rather not deviate from where the JS Community is fairly decided.
- When you can't use double quotes, try using back ticks (\`).
> Reason: These generally represent the intent of complex enough strings.
## Spaces
- Use 2 spaces. Not tabs
> Reason: More JavaScript teams do this (e.g. airbnb, idiomatic, standard, npm, node, google/angular, facebook/react). The TypeScript/VSCode teams use 4 spaces but are definitely the exception in the ecosystem.
### VS Code `settings.json`
```
// The number of spaces a tab is equal to. This setting is overridden
// based on the file contents when `editor.detectIndentation` is true.
"editor.tabSize": 2,
// Insert spaces when pressing Tab. This setting is overriden
// based on the file contents when `editor.detectIndentation` is true.
"editor.insertSpaces": true,
// When opening a file, `editor.tabSize` and `editor.insertSpaces`
// will be detected based on the file contents. Set to false to keep
// the values you've explicitly set, above.
"editor.detectIndentation": false
```
## Semicolons
- Use `semicolons`(;).
> Reasons: Explicit semicolons helps language formatting tools give consistent results.Missing ASI (automatic semicolon insertion) can trip new devs e.g. foo() \n (function(){}) will be a single statement (not two). TC39 warning on this as well. Example teams: airbnb, idiomatic, google/angular, facebook/react, Microsoft/TypeScript.
## Array
- Annotate arrays as `foos: Foo[]` instead of `foos: Array<Foo>`.
> Reasons: It's easier to read. It's used by the TypeScript team. Makes easier to know something is an array as the mind is trained to detect [].
## Filename
- Name files with `camelCase`. E.g. `accordion.tsx`, `myControl.tsx`, `utils.ts`, `map.ts` etc.
> Reason: Conventional across many JS teams.
- Exception: Follow the `nestjs` doc
## type vs. interface
- Use type when you might need a `union` or `intersection`:
```
type Foo = number | { someProperty: number }
```
- Use interface when you want extends or implements e.g.
```ts
interface Foo {
foo: string;
}
interface FooBar extends Foo {
bar: string;
}
class X implements FooBar {
foo: string;
bar: string;
}
```
> Otherwise use whatever makes you happy that day.
## MySQL Naming Conventions
- [Database-Naming-Convention](https://github.com/RootSoft/Database-Naming-Convention)
## Restful URLs Naming Conventions
- Naming should use **nouns**
- Response should not leak irrelevant implementation details out to you API
```
GET /tickets - Retrieves a list of tickets
GET /tickets/12 - Retrieves a specific ticket
POST /tickets - Creates a new ticket
PUT /tickets/12 - Updates ticket #12
PATCH /tickets/12 - Partially updates ticket #12
DELETE /tickets/12 - Deletes ticket #12
```
- Plural Nouns Are Preferable, Rather Than Singular
- e.g. `/users` is better than `/user` and `/users/16` is better than `/user/16`
- Relations
```
GET /tickets/12/messages - Retrieves list of messages for ticket #12
GET /tickets/12/messages/5 - Retrieves message #5 for ticket #12
POST /tickets/12/messages - Creates a new message in ticket #12
PUT /tickets/12/messages/5 - Updates message #5 for ticket #12
PATCH /tickets/12/messages/5 - Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5 - Deletes message #5 for ticket #12
```
- Represent Complex Parameters with a Query String
`GET /users?location=US&age=21` is better than
```
GET /users
GET /US-basedUsers
GET /US-basedUsersAnd21-agedUsers
```
- Avoid Using Underscores(`-`) in URLs, use hyphens(`-`) instead
- [RESTful API Design: Best Practices](https://gearheart.io/blog/restful-api-design-best-practices/)
- [Best Practices for Designing a Pragmatic RESTful API](https://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful)
## Git commit message
Sign in with Wallet
Connect another wallet