comments

README.md

@@ -234,4 +234,145 @@ function loadPages(count: number = 10) {
 }
 ```
 
-**[⬆ back to top](#table-of-contents)**
+**[⬆ back to top](#table-of-contents)**
+
+## Comments
+
+The use of a comments is an indication of failure to express without them. Code should be the only source of truth.
+  
+> Don’t comment bad code—rewrite it.  
+> — *Brian W. Kernighan and P. J. Plaugher*
+
+### Prefer self explanatory code instead of comments
+
+Comments are an apology, not a requirement. Good code mostly documents itself.
+
+**Bad:**
+
+```ts
+// Check if subscription is active.
+if (subscription.endDate < Date.now) {  }
+```
+
+**Good:**
+
+```ts
+const isSubscriptionActive = subscription.endDate < Date.now;
+if (isSubscriptionActive) { /* ... */ }
+```
+
+**[⬆ back to top](#table-of-contents)**
+
+### Don't leave commented out code in your codebase
+
+Version control exists for a reason. Leave old code in your history.
+
+**Bad:**
+
+```ts
+class User {
+  name: string;
+  email: string;
+  // age: number;
+  // jobPosition: string;
+}
+```
+
+**Good:**
+
+```ts
+class User {
+  name: string;
+  email: string;
+}
+```
+
+### Don't have journal comments
+
+Remember, use version control! There's no need for dead code, commented code, and especially journal comments. Use git log to get history!
+
+**Bad:**
+
+```ts
+/**
+ * 2016-12-20: Removed monads, didn't understand them (RM)
+ * 2016-10-01: Improved using special monads (JP)
+ * 2016-02-03: Added type-checking (LI)
+ * 2015-03-14: Implemented combine (JR)
+ */
+function combine(a:number, b:number): number {
+  return a + b;
+}
+```
+
+**Good:**
+
+```ts
+function combine(a:number, b:number): number {
+  return a + b;
+}
+```
+
+**[⬆ back to top](#table-of-contents)**
+
+### Avoid positional markers
+
+They usually just add noise. Let the functions and variable names along with the proper indentation and formatting give the visual structure to your code.  
+Optionally you can use IDE support for code folding (see Visual Studio Code [folding regions](https://code.visualstudio.com/updates/v1_17#_folding-regions)).
+
+**Bad:**
+
+```ts
+////////////////////////////////////////////////////////////////////////////////
+// Client class
+////////////////////////////////////////////////////////////////////////////////
+class Client {
+  id: number;
+  name: string;
+  address: Address;
+  contact: Contact;
+
+  ////////////////////////////////////////////////////////////////////////////////
+  // public methods
+  ////////////////////////////////////////////////////////////////////////////////
+  public describe(): string {
+    // ...
+  }
+
+  ////////////////////////////////////////////////////////////////////////////////
+  // private methods
+  ////////////////////////////////////////////////////////////////////////////////
+  private describeAddress(): string {
+    // ...
+  }
+
+  private describeContact(): string {
+    // ...
+  }
+};
+```
+
+**Good:**
+
+```ts
+class Client {
+  id: number;
+  name: string;
+  address: Address;
+  contact: Contact;
+
+  public describe(): string {
+    // ...
+  }
+
+  private describeAddress(): string {
+    // ...
+  }
+
+  private describeContact(): string {
+    // ...
+  }
+};
+```
+
+**[⬆ back to top](#table-of-contents)**