From 1f432cf5c03a97b0ccd3aa66969eb36548ad1a01 Mon Sep 17 00:00:00 2001
From: Benjamin Odom <bennybroseph@gmail.com>
Date: Tue, 28 May 2024 09:46:25 -0500
Subject: [PATCH] Create comments.md (#1498)

---
 docs/comments.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/comments.md

diff --git a/docs/comments.md b/docs/comments.md
new file mode 100644
index 00000000000..9610052adf2
--- /dev/null
+++ b/docs/comments.md
@@ -0,0 +1,64 @@
+## How do I comment my code?
+
+### While we're not enforcing a strict standard, there are some things to keep in mind:
+- Make comments meaningful
+ - Comments should be explaining why a line or block of code exists and what the reason behind it is
+ - Comments should not be repeating chunks of code or explaining what 'true' and 'false' means in typescript
+- Make sure comments exist on Functions, Classes, Methods, and Properties
+ - This may be the most important things to comment. When someone goes to use a function/class/method/etc., having a comment reduces the need to flip back and forth between files to figure out how something works. Peek Definition is great until you're three nested functions deep.
+ - The best example of this is JSDoc-style comments as seen below:
+   - When formatted this way, the comment gets shown by intellisense in VS Code or similar IDEs just by hovering over the text!
+   - Functions also show each the comment for parameter as you type them, making keeping track of what each one does in lengthy functions much more clear
+```js
+/**
+ * Changes the type-based weather modifier if this move's power would be reduced by it
+ * @param user {@linkcode Pokemon} using this move
+ * @param target {@linkcode Pokemon} target of this move
+ * @param move {@linkcode Move} being used
+ * @param args [0] {@linkcode Utils.NumberHolder} for arenaAttackTypeMultiplier
+ * @returns true if the function succeeds
+ */
+apply(user: Pokemon, target: Pokemon, move: Move, args: any[]): boolean {
+}
+
+/** Set to true when experimental animated sprites from Gen6+ are used */
+public experimentalSprites: boolean = false;
+
+/**
+ * Cures the user's party of non-volatile status conditions, ie. Heal Bell, Aromatherapy
+ * @extends MoveAttr
+ * @see {@linkcode apply}
+ */
+export class DontHealThePartyPlsAttr extends MoveAttr {
+}
+```
+You'll notice this contains an `{@linkcode Object}` tag for each parameter. This provides an easy type denomination and hyperlink to that type using VS Code's Intellisense. `@linkcode` is used instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.
+
+If you're interested in going more in depth, you can find a reference guide for how comments like these work [here](https://jsdoc.app)
+
+### What not to do:
+- Don't leave comments for code you don't understand
+ - Incorrect information is worse than no information. If you aren't sure how something works, don't make something up to explain it. Ask for help instead.
+- Don't over-comment
+ - Not everything needs an explanation. Try to summarize blocks of code instead of singular lines where possible. Single line comments should call out specific oddities.
+
+## How do Abilities and Moves differ from other classes?
+While other classes should be fully documented, Abilities and Moves heavily incoperate inheritance (i.e. the `extends` keyword). Because of this, much of the functionality in these classes is duplicated or only slightly changed between classes.
+### With this in mind, there's a few more things to keep in mind for these:
+- Do not document any parameters if the function mirrors the one they extend.
+  - Keep this in mind for functions that are not the `apply` function as they are usually sparce and mostly reused
+- The class itself must be documented
+  - This must include the `@extends BaseClass` and `@see {@linkcode apply}` tags
+- Class member variables must be documented
+  - You can use a single line documentation comment for these `/** i.e. a comment like this */`
+- `args` parameters must be documented if used
+  - This should look something like this when there are multiple:
+```ts
+/**
+...
+ * @param args [0] {@linkcode Utils.NumberHolder} of arenaAttackTypeMultiplier
+ *             [1] {@linkcode Utils.BooleanHolder} of cancelled
+ *             [2] {@linkcode Utils.BooleanHolder} of rWeDoneYet
+...
+*/
+```
\ No newline at end of file