docs: add style guide #1137
docs: add style guide #1137
Conversation
|
|
||
| ### Comments and Documentation | ||
|
|
||
| - Document all exported functions, types, and variables. |
There was a problem hiding this comment.
I agree we should enforce docs for exported stuff, but I think we should also strongly encourage docs for ANYTHING non-trivial
"Does the name of this thing tell me everything I could possibly need to know?"
-> yes: ok to skip doc
-> no: write a doc, regardless of whether it's exported
| - Keep functions small and focused | ||
| - Limit function length to ~50 lines where possible | ||
| - Place the most important functions at the top of the file | ||
| - Public functions that aren't methods should be placed in files with `_utils.go` suffix |
There was a problem hiding this comment.
This isn't always the case, i.e. constructors. Perhaps reword to say something like:
"Public static functions that lack a tight coupling to a specific struct should be placed in files with _utils.go suffix"
There was a problem hiding this comment.
Public static functions that lack a tight coupling to a specific struct (e.g. a constructor)
should be placed in files with _utils.go suffix
|
|
||
| ### Comments and Documentation | ||
|
|
||
| - Document all exported functions, types, and variables. |
There was a problem hiding this comment.
We should also enforce param docs for exported functions
|
|
||
| This document outlines the coding standards and best practices for our Go projects. | ||
|
|
||
| ### Code Organization |
There was a problem hiding this comment.
Consider adding a section about small files, in addition to small functions
Mega files that contain multiple structs are no good. If a struct is non-trivial, it ought to have a dedicated file
|
TODO: add guide for how configs and constructors should be created (use structs, pointers to struct, how to validate config and inject defaults when not present, etc). See this discussion |
Why are these changes needed?
Currently only added very bare bones style guide for golang.
Solidity still TODO: I'm not the best person to fill this in.
Checks