QEP 400: Code style and practice guidelines

[nyalldawson]

This QEP documents coding standards and conventions used throughout the QGIS code base. Developers are required to follow these standards when submitting code to QGIS.

It is initially intended as a formal description of CURRENT CODE PRACTICES ONLY, which can be later modified and revised (in an atomic manner) if we want to change any of these standards. As such, please refrain from using this initial request as a place to discuss changes to current practice. Rather, let's keep discussion focused on whether this is an accurate and complete description of our current coding practices. 👍

The end goal here is having a formal policy in place describing all our coding conventions, which will help ease new developers into contributing effectively to QGIS and remove some of the unspoken assumptions surrounding QGIS development.

[nyalldawson]

Note: I've arbitrarily restarted the number at 400 here -- this seems right after the restructuring of QEPs to PRs.

[uclaros]

Note: I've arbitrarily restarted the number at 400 here -- this seems right after the restructuring of QEPs to PRs.

Do we actually need to have a QEP numbering system that does not match the PR/issue number? It seems to me like a potential point of confusion and a burden to keep track of!
314 (being 100 * π) is an easy to remember number for the first PR based QEP :)

[nyalldawson]

@uclaros

Do we actually need to have a QEP numbering system that does not match the PR/issue number?

I can certainly change it, but keep in mind that we'll end up with big gaps in the numbers that way, since issues and pr numbering is shared but only prs will be QEPs. It's also possible now to have multiple prs target the same QEP (eg a future change to these specifications is modifying the same QEP from a different pr number). Given this, I don't see any benefit in forcing the numbering to match the first pr creating a new QEP.

[uclaros]

I can certainly change it, but keep in mind that we'll end up with big gaps in the numbers that way, since issues and pr numbering is shared but only prs will be QEPs. It's also possible now to have multiple prs target the same QEP (eg a future change to these specifications is modifying the same QEP from a different pr number).

Do we mind if there are gaps? We were using the issue number until now so gaps were inevitable.
Regarding multiple PRs for a single QEP we can have a QEP label applied to the main PR and keep referencing it by its number.

I'd rather have gaps in the numbering than having to search the closed PRs list for the last QEP number to increment, unless there's some simple way to automate this.

[elpaso]

@nyalldawson looks goo to me, thank you for taking care of this.

Should we also mention the use of (possibly redundant but explicit) std::as_const in for loops?

[troopa81]

Should we also include something about using the new settings API instead of the raw string Qt api?

[uclaros]

Some more coding conventions we use that are not listed:

• Header/license for each file
• Includes
  • Separate qgis from qt includes
  • Include moc file for qobjects
  • Include qt as #include <QMap> and not #include "qmap.h"
  • Prefer forward declaration if possible instead of including from within header files
• Use QStringLiteral for untranslated literals, QLatin1String for comparisons
• Don't use qDebug(), use QgsDebugError/QgsDebugMsgLevel (we still need to define some logic for which level < 1 to use)
• methods that are actually const should be marked const