|
| 1 | +# Coding Guidelines |
| 2 | + |
| 3 | +This document is an extension to [CONTRIBUTING](./CONTRIBUTING.md) and provides more details about the coding guidelines and requirements. |
| 4 | + |
| 5 | +## API & Design |
| 6 | + |
| 7 | ++ Code must be well structured: |
| 8 | + + packages must have a limited responsibility (different concerns can go to different packages), |
| 9 | + + types must be easy to compose, |
| 10 | + + think about maintainbility and testability. |
| 11 | ++ "Depend upon abstractions, [not] concretions". |
| 12 | ++ Try to limit the number of methods you are exposing. It's easier to expose something later than to hide it. |
| 13 | ++ Take advantage of `internal` package concept. |
| 14 | ++ Follow agreed-upon design patterns and naming conventions. |
| 15 | ++ publicly-exposed functions are named logically, have forward-thinking arguments and return types. |
| 16 | ++ Avoid global variables and global configurators. |
| 17 | ++ Favor composable and extensible designs. |
| 18 | ++ Minimize code duplication. |
| 19 | ++ Limit third-party dependencies. |
| 20 | + |
| 21 | +Performance: |
| 22 | + |
| 23 | ++ Avoid unnecessary operations or memory allocations. |
| 24 | + |
| 25 | +Security: |
| 26 | + |
| 27 | ++ Pay proper attention to exploits involving: |
| 28 | + + gas usage |
| 29 | + + transaction verification and signatures |
| 30 | + + malleability |
| 31 | + + code must be always deterministic |
| 32 | ++ Thread safety. If some functionality is not thread-safe, or uses something that is not thread-safe, then clearly indicate the risk on each level. |
| 33 | + |
| 34 | +## Testing |
| 35 | + |
| 36 | +Make sure your code is well tested: |
| 37 | + |
| 38 | ++ Provide unit tests for every unit of your code if possible. Unit tests are expected to comprise 70%-80% of your tests. |
| 39 | ++ Describe the test scenarios you are implementing for integration tests. |
| 40 | ++ Create integration tests for queries and msgs. |
| 41 | ++ Use both test cases and property / fuzzy testing. We use the [rapid](pgregory.net/rapid) Go library for property-based and fuzzy testing. |
| 42 | ++ Do not decrease code test coverage. Explain in a PR if test coverage is decreased. |
| 43 | + |
| 44 | +We expect tests to use `require` or `assert` rather than `t.Skip` or `t.Fail`, |
| 45 | +unless there is a reason to do otherwise. |
| 46 | +When testing a function under a variety of different inputs, we prefer to use |
| 47 | +[table driven tests](https://github.com/golang/go/wiki/TableDrivenTests). |
| 48 | +Table driven test error messages should follow the following format |
| 49 | +`<desc>, tc #<index>, i #<index>`. |
| 50 | +`<desc>` is an optional short description of whats failing, `tc` is the |
| 51 | +index within the test case table that is failing, and `i` is when there |
| 52 | +is a loop, exactly which iteration of the loop failed. |
| 53 | +The idea is you should be able to see the |
| 54 | +error message and figure out exactly what failed. |
| 55 | +Here is an example check: |
| 56 | + |
| 57 | +```go |
| 58 | +<some table> |
| 59 | +for tcIndex, tc := range cases { |
| 60 | + <some code> |
| 61 | + resp, err := doSomething() |
| 62 | + require.NoError(err) |
| 63 | + require.Equal(t, tc.expected, resp, "should correctly perform X") |
| 64 | +``` |
| 65 | +
|
| 66 | +## Quality Assurance |
| 67 | +
|
| 68 | +We are forming a QA team that will support the core Cosmos SDK team and collaborators by: |
| 69 | +
|
| 70 | +- Improving the Cosmos SDK QA Processes |
| 71 | +- Improving automation in QA and testing |
| 72 | +- Defining high-quality metrics |
| 73 | +- Maintaining and improving testing frameworks (unit tests, integration tests, and functional tests) |
| 74 | +- Defining test scenarios. |
| 75 | +- Verifying user experience and defining a high quality. |
| 76 | + - We want to have **acceptance tests**! Document and list acceptance lists that are implemented and identify acceptance tests that are still missing. |
| 77 | + - Acceptance tests should be specified in `acceptance-tests` directory as Markdown files. |
| 78 | +- Supporting other teams with testing frameworks, automation, and User Experience testing. |
| 79 | +- Testing chain upgrades for every new breaking change. |
| 80 | + - Defining automated tests that assure data integrity after an update. |
| 81 | +
|
| 82 | +Desired outcomes: |
| 83 | +
|
| 84 | +- QA team works with Development Team. |
| 85 | +- QA is happening in parallel with Core Cosmos SDK development. |
| 86 | +- Releases are more predictable. |
| 87 | +- QA reports. Goal is to guide with new tasks and be one of the QA measures. |
| 88 | +
|
| 89 | +As a developer, you must help the QA team by providing instructions for User Experience (UX) and functional testing. |
![mergify[bot]](https://avatars.githubusercontent.com/in/10562?v=4&size=40){kind=avatar}
0 commit comments