From a8542e6a43590b16d567b180abbcb707bbc39c2c Mon Sep 17 00:00:00 2001 From: Eugene Fox Date: Sun, 12 Nov 2023 14:52:34 +0300 Subject: [PATCH] Updated Code Style page (WIP) --- Code-style.md | 318 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 317 insertions(+), 1 deletion(-) diff --git a/Code-style.md b/Code-style.md index 2fd9f95..f7d3cb0 100644 --- a/Code-style.md +++ b/Code-style.md @@ -1 +1,317 @@ -TBD \ No newline at end of file +> 🚧 **Work in progress!** +> +> This page currrely is worked on. There may be some discrepancies or outdated information. Use VS Code and ESLint (`yarn lint`) for code formatting. + +# Overview +This article contains a set of rules and guidelines that you should follow when working on an issue. + +> ℹ️ **Advice** +> +> This repository has additional configuration files that contain some formatting rules and recommended extensions for VS Code editor. So, it is recommended to use VS Code editor during the development, since it that case it will be easier to follow these guidelines. + +# General + +## βš”οΈ Indentation and spacing +- **We use tabs**, not spaces. +- Separate logical blocks with empty lines +- Separate block statements (if/else, try/catch, switch, etc.) with empty lines +- Always place opening braces on a new line +- Always place conditional statement on the a new line + +```ts +// ❌ Incorrect +function GetMessage(key: string): string { + if (key.length) throw new Error("Empty string is not allowed"); + switch (key) { + case "success": return "Completed successfully"; + case "fail": return "Something went wrong"; + default: + + } +} +``` + +## βœ’οΈNaming conventions +The project inherits [.NET Naming Guidelines](https://learn.microsoft.com/dotnet/standard/design-guidelines/naming-guidelines) with some exceptions and additions. + +Use this table in addition to the main guidelines to determine what naming convention to use + +| `PascalCase` | `camelCase` | `_underscoredCamelCase` | +| --------------------- | ------------------------ | ----------------------- | +| All exported members | Local-scoped variables | Private variables | +| Files in `src` folder | Local-scoped constants | Private constants | +| | React hooks | Non-exported constants | +| | Files in `public` folder | Non-exported variables | +| | CSS-in-JS classes | | + +## πŸ“– Documentation +- All exported and public members must be documented using JSDoc syntax +- Other parts of code may be documented at will + +Overall, the more documentation there is, the better. + +```ts +/** + * Calculates amount of energy equal to provided mass + * @param mass Mass of an object in kilograms + * @returns Amount of energy in Joules + * @throws If mass is negative + */ +function GetEnergy(mass: number): number +{ + if (mass < 0) + throw new Error("Mass must be a non-negative value"); + + const speedOfLight: number = 3_0000_0000; // 3 * 10^8 m/s + + return mass * Math.pow(speedOfLight, 2); // E = mc^2 +} +``` + +## Strings +Always use "double quotes" for literal string values +```ts +// βœ… Correct +import React from "react"; +export const Message: string = "Hello, World!"; + +// ❌ Incorrect +import React from 'react'; +export const Message: string = 'Hello, World!'; +``` + +## Variables vs constants +- Always use either `let` or `const` keywords. Do not use `var` +- Use `const` when the value will not change. Otherwise, use `let` +```ts +function GetEnergy(mass: number): number +{ + // let speedOfLight: number = 3_0000_0000; // ❌ Incorrect + // var result: number = Math.pow(speedOfLight, 2); // ❌ Incorrect + const speedOfLight: number = 3_0000_0000; // βœ… Correct + let result: number = Math.pow(speedOfLight, 2); // βœ… Correct + + result = result * mass; + return result; +} +``` + +## Constants vs functions +- Use constants with arrow functions only when it's a one-liner: + ```ts + // βœ… Correct + const log = (...args: string[]): void => + console.log(...args) + + // βœ… Correct + async function GetData(): Promise + { + const response: Response = await fetch("https://example.com/api/data"); + return await response.json(); + } + ``` + ```ts + // ❌ Incorrect + const getData = async (): Promise => + { + const response: Response = await fetch("https://example.com/api/data"); + return await response.json(); + } + + // ❌ Incorrect + function PrintLog(...args: string[]): void + { + console.log(...args); + } + ``` +- Use constants when exporting React components with no logic. Otherwise use functions + ```tsx + // βœ… Correct + export const MyComponent = (props: IProps): JSX.Element => ( + + + + ); + + // βœ… Correct + export function MyComponent(): JSX.Element + { + const [data, setData] = useState({ }); + + useEffect(() => + { + fetch("https://example.com/api/data") + .then(res => res.json()) + .then(json => setData(json)); + }, []); + + return ( + + + + ); + } + ``` + ```tsx + // ❌ Incorrect + export const MyComponent = (): JSX.Element => + { + const [data, setData] = useState({ }); + + useEffect(() => + { + fetch("https://example.com/api/data") + .then(res => res.json()) + .then(json => setData(json)); + }, []); + + return ( + + + + ); + } + + // ❌ Incorrect + export function MyComponent(props: IProps): JSX.Element + { + return ( + + + + ); + } + ``` + +### Style +- Prefer to use lambda functions +- Always put curly braces on new lines + - Wrong: + ```js + if (condition) { + ... + } + ``` + - Correct: + ```js + if (condition) + { + ... + } + ``` + > **Note:** For JSON files put opening brace on the same line as the key +- Put spaces between operators, conditionals and loops + - Wrong: + ```js + y=k*x+b; + if(condition) { ... } + ``` + - Correct: + ```js + y = k * x + b; + if (condition) { ... } + ``` +- Use ternary conditionals wherever it's possible, unless it's too long + - Wrong: + ```js + var s; + if (condition) + s = "Life"; + else + s = "Death"; + ``` + - Correct: + ```js + var s = condition ? "Life" : "Death"; + ``` +- Do not surround loop and conditional bodies with curly braces if they can be avoided + - Wrong: + ```js + if (condition) + { + console.log("Hello, World!"); + } + else + { + return; + } + ``` + - Correct + ```js + if (condition) + console.log("Hello, World!"); + else + return; + ``` +- Prefer export modules as default + - Wrong: + ```js + export class MyClass { ... } + ``` + - Correct: + ```js + export default class MyClass { ... } + ``` +- Prefer export modules as classes unless it is excessive + - Wrong: + ```ts + export function MyFunction1() { ... } + export function MyFunction2() { ... } + export default class MyClass2() + { + public static GetDate(timestamp: number): Date + { + return new Date(timestamp); + } + } + ``` + - Correct: + ```js + export default class MyClass1 + { + public static MyFunction1() { ... } + public static MyFunction2() { ... } + } + export default GetDate(timestamp: number): Date + { + return new Date(timestamp); + } + ``` +- When JSX attributes take too much space, put each attribute on a new line and put additional line before component's content + - Wrong: + ```tsx + My content here + My content here + + My content here + + + My content here + + ``` + - Correct: + ```tsx + + + My content here + + ``` +- If JSX component doesn't have content, put space before closing tag + - Wrong: + ```tsx + + ``` + - Correct: + ```tsx + + ```