From 7a2c6b8828e4e00baa3dddfbe4c7a38b8eade8f5 Mon Sep 17 00:00:00 2001 From: Bertie690 Date: Mon, 28 Apr 2025 23:41:37 -0400 Subject: [PATCH] Fixed up documentation for comments.md and linting.md Comments.md added info pertaining to Kev's review linting.md i just stopped spouting misinformation --- docs/comments.md | 39 ++++++++++++++++++++++++++------------- docs/linting.md | 7 ++++--- 2 files changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/comments.md b/docs/comments.md index 78b0b0559e2..fe49cb78678 100644 --- a/docs/comments.md +++ b/docs/comments.md @@ -1,37 +1,46 @@ # Commenting code -People spend more time reading code than writing it (sometimes substantially more so). As such, comments and documentation are **vital** for any large codebase like this. +People spend more time reading code than writing it (sometimes substantially more so). As such, comments and documentation are **vital** for any large codebase like this to function. ## While we're not enforcing a strict standard, here are some things to keep in mind: - Make comments meaningful - - Comments should explain _why_ a line or block of code exists - its "raison d'être", if you will. - - Comments should not repeat chunks of code or explain concepts obvious to the average reader like the meaning of `&&=` or `??` -- Make comments readable - - The length of a comment should roughly scale with the complexity of whatever it is describing. Small quips are fine for inline comments and explanations, but summarizing a 300 line function with "Starts a battle" is about as good as doing nothing. - - Long comments should ideally be broken into multiple lines at around the 100-120 character mark. + - Comments should **NOT** repeat _what_ code _does_[^1] or explain concepts obvious to someone with a basic understanding of the language at hand. Instead, focus on explaining _why_ a line or block of code exists - its "raison d'être", if you will. + - Anyone with basic reading comprehension and a good IDE can figure out what code does; gaining a _post hoc_ understanding of the _reasons_ behind its existence takes a lot more digging, effort and bloodshed. +- Keep comments readable + - A comment's verbosity should roughly scale with the complexity of its subject matter. Some people naturally write shorter or longer comments as a personal style, but summarizing a 300 line function with "does a thing" is about as good as writing nothing. Conversely, writing a paragraph-level response where a basic one-liner would suffice is equally unhelpful. + - Long comments should ideally be broken into multiple lines at around the 100-120 character mark. This isn't _mandatory_, but avoids unnecessary scrolling in terminals and IDEs. - Make sure comments exist on Functions, Classes, Methods, and Properties - These 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 what XYZ does. Peek Definition is great until you're three nested levels deep. - - The best example of this is TSDoc-style comments as seen below: - - When formatted this way, the comment gets shown within VS Code or similar IDEs just by hovering over the function! - - Functions also show the comment for each parameter as you type them, making keeping track of arguments inside lengthy functions much more clear. +[^1]: With exceptions for extremely long, convoluted or unintuitive methods (though an over-dependency on said comments is likely asymptomatic of poorly structured code). + +Given all this, look at the following + +# TSDoc +Taking all these together, one notable example of good comments are those adhering to the TSDoc standard. These comments (frequentl) +When formatted this way, these comments are shown within VS Code or similar IDEs just by hovering over the function! +- Functions also show the comment for each parameter as you type them, making keeping track of arguments inside lengthy functions much more clear. + +## Syntax +For an example of how TSDoc comments work, here are several real examples of TSDoc comments at work, taken from various files inside this very repo[^2]: ```ts /** * Change the type-based weather modifier if this move's power would be reduced by it. * @param user - The {@linkcode Pokemon} using this move * @param target - The {@linkcode Pokemon} being targeted by this move * @param move - The {@linkcode Move} being used (unused) - * @param args - [0]: A {@linkcode NumberHolder} for arenaAttackTypeMultiplier + * @param args - [0]: A {@linkcode NumberHolder} for `arenaAttackTypeMultiplier` * @returns - Whether the move effect was applied successfully */ apply(user: Pokemon, target: Pokemon, move: Move, args: [NumberHolder, ...any]): boolean { } -/** Class containing */ +/** Class containing configurable user settings. */ class Settings { /** Set to `true` when experimental animated sprites from Gen6+ should be used */ public experimentalSprites: boolean = false; } + /** * Cure the user's party of non-volatile status conditions, ie. Heal Bell, Aromatherapy */ @@ -39,15 +48,19 @@ 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. + +Looking at the example given, you'll notice this contains an `{@linkcode XYZ}` tag for each parameter. This provides an easy type denomination and hyperlink to that type in most modern IDEs. (`@linkcode` is used here instead of `@link` so that the text appears in monospace which is more obviously a `type` rather than a random hyperlink.) \ +Also note the dashes (` - `) between the parameter names and descriptions - these are **mandatory** under the TSDoc spec[^3]. If you're interested in going more in depth, you can find a reference guide for how comments like these work [here](https://tsdoc.org). +[^3]: Incidentally, this is also the only place dashes are explicitly _required_. + ### 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 and/or mark it as TODO. - 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 or features. + - Not everything needs a comment. Try to summarize blocks of code instead of singular lines where possible, always preferring giving a reason over stating a fact. Single line comments should call out specific oddities or features. ## 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. diff --git a/docs/linting.md b/docs/linting.md index c4dcef226cf..d3b4e47675f 100644 --- a/docs/linting.md +++ b/docs/linting.md @@ -41,7 +41,6 @@ A full list of flags and options can be found on [their website](https://biomejs - `--write` will cause Biome to write all "safe" fixes and formatting changes directly to your files (rather than just complaining and doing nothing). - `--changed` and `--staged` will only perform checks on all changed or staged files respectively. Biome sources this info from the relevant version control system (in this case Git). -- `--only=XXX` will filter reported lint issues to a specific category or rule name. Useful for checking errors after Lefthook flags your code (summary screen doesn't show exact line numbers). - `diagnostic-level=XXX` will only show diagnostics with at least the given severity level (`info/warn/error`). Useful to only focus on errors causing a failed workflow run or similar. ## Linting Rules @@ -54,11 +53,13 @@ Some things to consider: - Some rules are currently disabled or marked as warnings (`warn`) to allow for gradual refactoring without blocking development. **Do not write new code that triggers these warnings.** - The linter is configured to ignore specific files and folders (such as excessively large files or ones in need of refactoring) to improve performance and focus on actionable areas. -Any questions about linting rules should be brought up in the `#dev-corner` channel in the discord. +Any questions about linting rules should be brought up in the `#dev-corner` channel in the discord. [^1]: A complete list of rules can be found in the `biome.jsonc` file in the project root. ## What about ESLint? -Our project migrated away from ESLint around March 2025 due to it simply not scaling well enough with the codebase's ever-growing size. The [existing eslint rules](../eslint.config.js) are considered _deprecated_, only kept due to Biome lacking the corresponding rules. \ No newline at end of file +Our project migrated away from ESLint around March 2025 due to it simply not scaling well enough with the codebase's ever-growing size. The [existing eslint rules](../eslint.config.js) are considered _deprecated_, only kept due to Biome lacking the corresponding rules in its current ruleset. + +No additional ESLint rules should be added under any circumstances - even the few currently in circulation take longer to run than the entire Biome formatting/linting suite combined. \ No newline at end of file