Design Guidelines

Changes on the cxx plugin should follow the below design guidelines:

in general

• follow the Clean Code Developer approach, the main ideas are listed here
• 'eat your own dog food': use SonarQube to avoid adding technical debt
• follow the 'boyscout rule': always leave the code better than you found it
• provide automatized Unit Tests
• features without documentation are useless: describe always what the feature does and how it can be used (extend the Wiki)
• keep it simple, stupid (KISS)
• Zero-overhead principle: Add additional features always in a way, that you don't pay for (performance degradation) what you don't use.

cxx plugin

• the main purpose of the cxx plugin is to forward reports from 3rd party tools to SonarQube
  • we don't like to reinvent the wheel
• the cxx plugin expects to be fed with syntactically correct code
  • use an external compiler to get detailed syntax and semantic issues
• the cxx plugin is responsible for indexing the source code files
• the cxx plugin is responsible for syntax highlighting
• the cxx plugin is responsible to create software metrics
• the cxx plugin is responsible to forward issues from reports of 3rd party tools

erroneous configuration:

• in case of an erroneous configuration the scanner should stop with an error
  • should not create a new snapshot on the SonarQube Server
• configuration errors are recorded in the scanner LOG file
• configuration errors should not lead to technical debt

strategy for cxx grammar extensions

1. prefer grammar extensions using the preprocessor, see Dealing with compiler specific code pieces
2. if 1. is not possible and extension does not conflict with 'C/C++ standard' extension of grammar is allowed.

source code parsing:

• we support a tolerant and strict error handling mode sonar.cxx.errorRecoveryEnabled
  • in tolerant mode (True) syntax errors within a declaration are skipped, analysis is continued with next declaration in source code file
  • in strict mode (False) analysis of source code file fails after a syntax error. Source code file is ignored.

erroneous reports:

• we support a tolerant and strict error handling mode sonar.cxx.errorRecoveryEnabled
  • in tolerant mode (True) analysis continue in case of errors in a report file
  • in strict mode (False) an error in a report file will stop the analysis

logging

• avoid too much .LOG output, even in DEBUG mode
• add only the absolutely necessary messages to track the internal steps of the plugin
• do not repeat information
• information that is also available in the SonarQube UI should not be written to the .LOG file (e.g. every single added issue)
• special states and error conditions should all be reported (e.g. can't open file, rule does not exist)