# TypeScript/Solidity Style Guide Discussion
While we’re all in the same place next week let’s come to an agreement on some general style guidelines! Code style itself shouldn’t be an end goal but a consistent style will make our codebase more readable and cohesive and it will easier to onboard new folks.

Lots of styling discussion can end up as [bikeshedding](https://en.wikipedia.org/wiki/Law_of_triviality) which can be annoying but if we make these decisions as a team ahead of time we can put them aside and get back to building awesome software!

# Example Style Guides
* [thoughtbot Style Guides](https://github.com/thoughtbot/guides/tree/master/style) (wherein may lie some of biases 😉)
* [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
* [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript)
* [Idiomatic JavaScript Style Guide](https://github.com/rwaldron/idiomatic.js/)
# Topics to discuss

## Overview
* Just like security is never perfect code orginization and style is never perfect either. If we're thinking and talking about these things we're already way ahead of the pack.
* Code style shouldn't be an end goal in itself but a means to an end.
* Good stuff from the Idiomatic JavaScript Style Guide
* All code in any code-base should look like a single person typed it, no matter how many people contributed.
* Arguments over style are pointless. There should be a style guide, and you should follow it
* Consistency Always Wins: It's important to note that formatting preferences, such as "inner whitespace" should be considered optional, but only one style should exist across the entire source of your project.
* Code style needs to have a collective buy-in instead of having "style police" to enforce the rules. See: https://twitter.com/ZacSweers/status/1233106528112201729

## Quick wins to consider

* Fix Solidity warnings
* Add a STYLEGUIDE.md to the monorepo. Luckily a lot is covered by the linter but not everything.
* Be willing to make small refactors in your every day work

## Medium Term
* Take stock on our repo structure: Can anything be pulled out into it's own repo? Can anything be merged? If core utils are only used by one project should they live in core utils or that project?
## Things to keep in mind in the future

* Keep dependencies as up to date as possible
* Update to latest Solidity

## Things to discuss
### Inline comments
Inline comments serve many different purposes. We should decide as a team when and when not to use them.

##### Pros
* Can describe the functionality of code
* Gives our codebase personality and life
* Leaving in existing inline comments will save time

##### Cons
* [Good article](https://blog.codinghorror.com/coding-without-comments/) by Jeff Atwood on why to avoid inline comments in a lot of cases

* [Another blog](https://www.tomdalling.com/blog/coding-styleconventions/why-inline-comments-are-generally-a-bad-idea/) article which I think makes some good suggestions
* Avoid comments that explain "what" the code does.

* Only include "why" comments if they are of decent value to developers maintaining the code.

* Always delete code that has been commented out. If you really need the old code, it should be available from your version control software anyway.
* From the PEP8 Python style guide
* Bad: `x = x + 1 # Increment x`
* Good: `x = x + 1 # Compensate for border`

### TypeDoc

Currently some of our code has TypeDocs and some of our code doesn’t. We should probably commit to have TypeDocs on everything or not having TypeDocs. We could also decide that in certain cases we need TypeDoc (ie all new code needs TypeDoc or all public facing interfaces need TypeDoc).

#### Pros
* Gives new teammates and external people information of how to use libraries

#### Cons
* Takes time to write
* Spending time on TypeDoc isn't inline with the [agile manifesto](https://agilemanifesto.org/) ("Working software over comprehensive documentation")

### Lodash

Lodash can help us write clearer more concise JavaScript. Adding dependencies should be done with caution though.

#### Pros
* Code can be cleaner and more concise

#### Cons
* Security vulnerabilities
- Bundle Size

## Anything else?

## Action Items (short term)
- Fix Solidity warnings (Mason)
* Fix long line length (Mason)
* Add "Other Changes" section to the github PR template (Mason)
* Add calendar event to discuss style again next month (Mason)
* Pull out game sematics repo into it's own repo (Ben)
* - Add a STYLEGUIDE.md to the monorepo. Luckily a lot is covered by the linter but not everything.

## Action Items (long term)
- Keep dependencies as up to date as possible
* Update to latest Solidity

## Next Agenda