link_formatting.adoc

Why is it important to define a standard for links?

We often want to provide links in the 'Resources' section of a rule that point to blog posts, documentation, and other rules. To provide a consistent experience across the Sonar solution, we want to define standard ways to write these links in our rules. This document aims to do that. This guidance does not apply to links that appear within continuous text elsewhere in a rule.

How should you write links?

Link formatting:

• Links to documentation: <source> - <title> e.g. SonarQube Documentation - SonarScanner for Gradle

• Links to framework documentation <source> - <member name and kind> e.g. Microsoft Learn - Object.ToString Method

• Links to blog posts / news articles: <source> - <title> e.g. Google Security Blog - Moving towards a more secure web

• Links to Stack Overflow answers (similar comments in a blog)e.g. Stack Overflow - Answer by Stephen Cleary for Best way to handle null task inside async method?

• Links to another Sonar rule: <rulenumber> - <title> e.g. S2755 - XML parsers should not be vulnerable to XXE attacks. Note that rule-ids (<rulenumber>) are automatically hyperlinked in our products to point to the rule description in that product. Do not add any hyperlink yourself.

The hyperlink to anything apart from other Sonar rules should be applied to just the document name, with the 'source' being left as plain text. The idea is that this makes it really easy for a user to understand the source before they click on anything. For Sonar rules, the whole entry (<rulenumber> - <title>) should be a hyperlink.

Here is how the above links should look like:

• SonarQube Documentation - SonarScanner for Gradle

• Microsoft Learn - Object.ToString Method

• Google Security Blog - Moving towards a more secure web

• Stack Overflow - Answer by Stephen Cleary for Best way to handle null task inside async method?

• S2755 - XML parsers should not be vulnerable to XXE attacks
  Note, no link here, this is the intended behavior. In the products the "S2755" part will be automatically hyperlinked.

Additional things to consider when adding a link to a rule:

• Is the article (particularly blog posts) likely to be around for at least 6 months?

• Do you trust this source as an 'expert'?

• Link to en_US versions where there is a choice

Short form names for sources we regularly use

When web pages have massively long names like "Java™ Platform, Standard Edition 8 API Specification", we will provide short form names that we will use instead. Feel free to add new ones below:

Short form names to use:

• Android Documentation - https://developer.android.com/docs

• Apex Developers Guide - https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_keywords_sharing.htm

• AWS Documentation - https://docs.aws.amazon.com/

• AWS blog - https://aws.amazon.com/blogs

• Azure Documentation - https://learn.microsoft.com/en-us/azure/?product=popular

• CERT - https://wiki.sei.cmu.edu/confluence/display/seccode

• C++ reference - https://en.cppreference.com/w/

• C++ Core Guidelines - https://github.com/isocpp/CppCoreGuidelines/blob/e49158a/CppCoreGuidelines.md

• CVE - https://cve.mitre.org

• CWE - https://cwe.mitre.org

• Docker Documentation - https://docs.docker.com/

• Google Cloud - https://cloud.google.com/docs

• Java Documentation - https://docs.oracle.com/en/java/

• Kotlin Documentation - https://kotlinlang.org/docs/home.html

• Kubernetes Documentation - https://kubernetes.io/docs/home/

• Microsoft Learn - https://learn.microsoft.com/en-us/

• Microsoft Developer Blog - https://devblogs.microsoft.com/

• MDN web docs - https://developer.mozilla.org/en-US/

• Medium - https://medium.com/

• MITRE - https://attack.mitre.org/

• Mockito - https://site.mockito.org/javadoc/current/overview-summary.html

• The Open Group - https://www.opengroup.org/

• OWASP - https://owasp.org/

• PEP - https://peps.python.org/

• PHP Documentation - https://www.php.net/docs.php

• PHP Tutorials - https://www.phptutorial.net/

• PEP 8 - Style Guide for Python Code - https://peps.python.org/pep-0008/

• Python Documentation - https://docs.python.org/

• React Documentation - https://reactjs.org/

• Rhino Security Labs - https://rhinosecuritylabs.com/

• SAP Documentation - http://help.sap.com/abapdocu_702/en/abenabap.htm

• SonarQube Documentation - https://docs.sonarqube.org/latest/

• Sonar - https://www.sonarsource.com/

• Sonar Blog - https://www.sonarsource.com/blog/

• Stack Overflow - https://stackoverflow.com/

• Symfony - https://symfony.com/doc/current/index.html

• Test NG Documentation - https://testng.org/doc/documentation-main.html

• W3Schools - https://www.w3schools.com/

• WCAG - https://www.w3.org/WAI/standards-guidelines/wcag/

• Wikipedia - https://en.wikipedia.org