Create comments.md (#1498)

This commit is contained in:
Benjamin Odom 2024-05-28 09:46:25 -05:00 committed by GitHub
parent fcdac63759
commit 1f432cf5c0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 64 additions and 0 deletions

64
docs/comments.md Normal file
View File

@ -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
...
*/
```