QtCS2017 Qt Examples Guidelines

Purpose of this discussion

• Define what a good example is
  • Coding guidelines
    • Use of the auto keyword
    • Consensus is to use the same guidelines as in Qt
  • Translations?
    • Should we use tr() in examples, even if they are never translated?
    • Consensus: Yes, let's keep that, because it is best practice
  • https://wiki.qt.io/Writing_Qt_Examples needs cleanup
    • signals and slots: prefer template style
    • List from the examples revamping project
    • Refer to the coding style document instead of duplicating where appropriate
    • Fix <code> tags
  • Qt Namespace
    • Do examples need to support namespaced Qt?
    • QT_BEGIN_NAMESPACE, QT_END_NAMESPACE is ugly
    • Summary: Rather skip examples for namespaced qt build
  • C++ standard: ??
    • Suggestion: Should just use the one Qt supports
    • Disagree: If there are ways to be better code, examples should advocate this
    • Examples don't have to support every single platform, can be disabled
    • Using newer C++ features might be a good thing, so we recommend best practices
    • But be conservative, let's not use it as playground for your-favorite-feature of the day
  • Qt Quick examples? Designer?
  • using namespace std?
  • Should work on all targets unless stated
    • What to do with those that don't
  • Should be self-contained
• Should we move some examples to demos repository?
  • We had demos, examples distinction in in Qt 4, but that got removed in Qt 5
  • We've now recreated separate demo repositories. Are there examples we'd like to move over?

• Who is responsible for writing and maintaining examples?
  • Lots of them look outdated, and/or do not advocate nowadays recommendation style
  • Who should maintain the examples? The module maintainers
  • Usually it's better to ask someone else, because the maintainer might be too deep into the topic
  • But it's the job of the original implementer of a feature to add an example
  • Can we collect suggestions from Support?

• Who is responsible for maintaining the examples guidelines?

• Examples and dependencies
  • Move examples that requires this to the documentation repository

• Outdated examples
  • What's outdated?
    • examples from deprecated modules
    • outdated look is not enough
    • Examples that were once 'cool' but don't have an educational purpose anymore (Tetris)
  • Suggestion: Keep a link, description and screenshot (if applicable) on the wiki and remove it from the repository
  • Alternative: Use separate qdoc file for outdated examples
  • Outcome: Just remove them