QtCS2017 Qt Examples Guidelines

From Qt Wiki
Revision as of 14:24, 10 October 2017 by Kkoehne (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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