docs: guideline improvements

docs/guides/guidelines.md

@@ -1,24 +1,32 @@
-This document explains guidelines that developers should follow, as well as offering device for building clean, maintainable code.
+This document explains guidelines that developers should follow when contributing to the TuringBot codebase, as well as offering advice for building clean, maintainable code.
 
 # Comments
 
 Please refer to the resources list at the bottom of this section for more commenting guidelines.
 
-Code should be thouroughly commented and documented, especially the `core`. Docstrings should be used liberally, and should be in the following locations.
+Code should be thoroughly commented and documented, especially the `core`. 
 
-- At the top of files. This docstring should contain a high level summary of the code contained in the file. The below example is for a `ping` module
+The quality of comments is more important than the quantity. Comments that are added purely for the sake of more comments should be avoided. If a comment doesn't directly clarify the surrounding context, it should be improved or removed. 
+
+- Good comments should explain *why* a piece of code exists, and enable developers to make connections to other pieces of code.
+- If you find a piece of code hard to comment, then that can indicate that the code is not very high quality, or easy to understand. 
+- Comments require maintenance, and good comments will require minimal upkeep as the code develops and changes.
+- Comments should be written for someone reading the code for the first time. As developers write comments for code, they have the full context of the surrounding code in their mind. They have a deep understanding of every part of the code, which can lead to bad comments. If a developer writes comments assuming the next person to read them fully understands everything that the developer did when they wrote the comment, then the comments will not be as helpful.
+- Please follow the practices posted [here](https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/) for more documentation.
+
+## Standard Documentation
+- File docstrings should contain a high level summary of the code contained in the file. Module files should have a link to all exported modules.
 
 ```typescript
-/*
+/**
  * Command that sends an embed containing uptime, meant to indicate that the bot is running.
+ * Modules:
+ *   {@link ping}
  */
 ```
 
-- Variable definitions. This docstring should at minimum contain a type.
-- Class definitions. This docstring should contain a description of the class
-- Function definitions. This docstring should explain what the function does, as well as the types of all arguments and return values.
+- Any region that you feel needs improvement, or was left unfinished can be marked with a `// TODO: comment`.
 
-There are more usecases where docstrings might be used, but they should be used in all the above cases unless you are confident it is not needed. Should you need to add comments later, mark the relevant section with a `TODO` comment.
 
 Comments should adhere to the best practices linked below
 
@@ -31,44 +39,46 @@ Comments should adhere to the best practices linked below
 - https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
 - https://mitcommlab.mit.edu/broad/commkit/coding-and-comment-style/
 
-# Whitespace
-
-## Spaces
-
-- There should be one space after a comma, none before. A newline may also be used if you are formatting an object or array with JSON style formatting, with a newline after every declaration.
-- There should be one space on either side of an assignment operator or boolean comparison. Correct formatting of this will be structured similar to `val = thing`, or `val >= thing`.
-- Statements (`if`, `for`, `while`, `function` are to be formatted with a space between the identifier, the arguments, and the context. Correct formatting may look like:
-
-```javascript
-if (val == thing) {
-  doTheThing();
-}
-```
-
-## Tabs
+# Code Style
+All submitted code should conform to the Google Typescript/Javascript style guide. If a piece of code does not, include documentation explaining why. 
 
-- Tabs are to be composed of 4 spaces.
+Please see the [Google Typescript Style Guide](https://google.github.io/styleguide/tsguide.html), referring to the [Google Javascript Style Guide](https://google.github.io/styleguide/jsguide.html), where the Typescript style guide is not sufficient.
 
-## Newlines
+## Key Points
+The below does not include everything, and is simply a collection of important parts of the style guide.
+- Variables are defined using `const`, unless they need to be reassigned, in which case they must be declared, using `let`. `var` is not acceptable.
+- Tabs take the form of *two spaces*.
+- Newlines are *LF*, not *CRLF*.
+- Variables, functions, parameters, functions, methods, and properties are `camelCase`. This includes local constants, and variables that are immutable by chance.
+- Global constants that should *never change* are `SCREAMING_SNAKE_CASE`. Examples of a variable that may be named using `SCREAMING_SNAKE_CASE` include:
+  - Magic Numbers (EX: `FOO_BAR = 0x12345`)
+  -  Asset URLs (EX: `EMBED_ICON = 'https://foo.bar/icon.png'`)
+  - File Paths (EX: `CONFIG_PATH = '../../config.jsonc'`) 
+- Classes, enums, types, type parameters, interfaces, are `PascalCase`.
 
-- Newlines are to be LF.
-- Preferred syntax for files includes two or more newlines after library inclusions, one newline after function declarations, and wherever needed to seperate code into logical sections.
 
 # Variable Names
 
 Proper variable naming greatly contributes to the readability and maintainability of code. Names should not be abbreviated in the core, and abbreviation should be kept to a minimum during module development, especially regarding function calls.
 Some general rules to follow:
 
-- Names should denote single values vs plural values. If a name is denoting type, it's generally not a good variable name. Where a good name for an array of dog names might be `dogs`, a bad name could be `dog` or `dogsArray`.
-- Names should generally be pronounceable, if you can't pronounce a variable name, it may not be a good description of the purpose of the variable.
-- Don't use different words for the same meaning. Having variables named `parsedData`, `processedDta`, and `parsedData` can lead to confusion, and is an indication of badly named variables.
-- Functions should be a verb or verb phrase (generally a verb followed by a noun).
+- Names should denote single values vs plural values. If a name is denotes the type of the variable, it's generally not a good variable name. Where a good name for an array of dog names might be `dogs`, a bad name could be `dog` or `dogsArray`.
+- Don't use different words that have the similar meanings. Having variables named `parsedData`, `processedData`, and `formattedData` can lead to confusion, and is an indication of a badly named variable
+- Functions should be a verb or verb phrase (generally a verb followed by a noun). An example of a good function name might be `missDuck`, or `formatDenyEmbed`
 
-## Resources
+## Variable Naming Resources
 
-https://betterprogramming.pub/clean-code-naming-b90740cbae12
+https://betterprogramming.pub/clean-code-naming-b90740cbae12<br>
 https://www.rithmschool.com/blog/good-ideas-for-better-variable-names
 
 # Commit messages
 
-Commit messages should follow the format `(sectionOfCodeChanged): description of what section of code was changed, and why. A good example of this might be `(core): fixed bug with exampleFunctionCall failed when fooing`. A bad example might be `(core): small fixes and improvements`.
+All commit messages should conform to the [Conventional Commit Standard](https://www.conventionalcommits.org/en/v1.0.0/).
+
+# Broad Code Quality
+
+Code quality is extremely difficult to define as an objective metric. Rather than attempt to create minimum standards or define vague, amorphous ideas that are hard to apply in practice, I'll lay out a few general ideas that can be kept in mind when writing code, that should helpfully improve the end product.
+
+- Focus on the connections between different parts of code, rather than the actual content of the code. Writing code that enables developers to create simple mental maps, and easily understand connections between different parts code will make further development easier, and result in higher quality code.
+- Prioritize the human over the computer. As developers become deeply engrossed in a problem, they start thinking on a level more closely to how computer interprets code. This can enable developers to solve complex problems, but it can also lead to unintuitive, unclear code that takes time to understand. If you can write your code and comments in a way that make the thought process easier to understand. Comments should prioritize explaining the impact of the code, rather than what the code is doing (code that makes use of advanced concepts may benefit from a functional explanation). 
+- Good code is written with the idea that someone else is going to need to read your code.