This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.
No over abstracting / future thinking. To guide your decision, you can ask yourself / others these questions:
- Explain the benefits of the abstraction to others, and see if they understand or think it's actually valuable.
- Ask yourself, when will the benefit of the proposed abstraction actually happen? If the answer is >= 1 year down the line or in rare situations, don't do it. The cost of doing this is complexity in understanding the code and added time in development + testing.
Convention over customisation / refactoring. There are several parts of the code base which are not ideal.. however, you must still follow them since it makes it easier to review and maintain the code. If you really want to refactor some part, create a different PR for it and refactor that code throughout the entire codebase. There are exceptions to this rule - when your proposed customisation / refactor is 10x better than the current way of doing things, then go ahead and do it anyway.
Before starting to code, find some other part of the code base that does a similar operation, and follow that as much as possible.
Coding is the last thing to be done. First we must understand the problem, then propose a solution, then think of API changes or architecture changes, discuss them with the team, then understand the types needed (very important - see "type thinking" section), and then we code.
Write as many comments as you can. Especially for parts which are tricky. This may seem like an obvious advice, however, it's really hard to follow.
The more explicit / clear a variable name is, the better. Something like
pointerToLastNodeis better than
Isolate classes / functions as much as possible. For example, if a function is only applicable for use within a recipe and not other places, then put that function in the utils file in that recipe folder, and not in the global utils file.
All source code should have a copyright notice on top of the file.