Notions And Actions on Code Quality

Vapor code quality isn’t in an ideal state. Here are some notions and actions on this topic. Also, this document is likely to be an WIP with people's thoughts keep being added.

Comment Policy

• Simple debug code that's only a few lines should be removed before merge.
• Complicate functionalities that facilitate debug could stay in its own function, and not be commented out. For example, one could have a debug-purpose function void TestCurrentStateOfProgram() that's not called.
• Blocks of code that is currently not in use but has potential use in the future should be commented out using #if 0 with a time stamp. The following code block is an example.

#if 0  // June 4th 2018
void OldDVR()
{
    // Some old implementation
}
#endif

Three-step Feature Testing.

• We adopt a three-step testing workflow:
  • Self test of a feature after finishing that feature development (on feature branch).
  • Group test of a feature after self test (on feature branch). This feature branch could then be merged to master.
  • Final round of test before release.
• Platforms: On each round of test, we should test on two of our very accessible platforms: macOS and Ubuntu Linux.

Compiler Warnings

• Warning are good indicators that the code could be improved, so we should aim to achieve warning-free in VAPOR code, in both RELEASE and DEBUG compilation mode.
• Warning suppression flags should be added with extreme caution and deliberate discussion.
• Un-resolved warnings should be left in the code base on a case-by-case basis, and with extreme caution.
• Platforms: Whichever strictness level we adopt, we should target it on two of our very accessible platforms: macOS and Ubuntu Linux.

Github Issues

• We agree to reduce the number of open issues.
• We don't know how to reduce it though.
• We agree to dedicate some time in the future to try to fix bugs.