Quick Links

• Summary of current status
• Spreadsheet of current status

Something that really stands out to me when working on Pencil’s code is that there is no universal code style. While there are certain conventions that are more prevalent than others, it seems that it is never universally consistent. Since I think that everyone will agree that any style is better than no style at all, I compiled a list of the various conventions in use so we can have a discussion as to what to use (I’m aware I might be opening Pandora’s box here). Once there is consent on the style to use, we can unify the style of the existing code and add an editorconfig to help new contributors stay consistent with it (Qt Creator plugin available at editorconfig/editorconfig-qtcreator). I’d happily volunteer to take care of the unification and the editorconfig myself.

Ordering is arbitrary, numbers are only there to make it easier to refer to a particular item if necessary.

1. Indentation
   1. four spaces per indent (currently prevalent by far)
   2. one tab per indent
2. End of file
   1. No newline at end of file
   2. One newline at end of file (currently prevalent by far)
   3. Two newlines at end of file (why would anyone want that?)
3. Whitespace in parentheses
   (sometimes also in other kinds of brackets)
   1. One space after each opening parenthesis and before each closing parenthesis: ( example ) (currently prevalent)
   2. No spaces after opening parenthesis or before closing parenthesis: (example)
4. Whitespace before parentheses
   (sometimes also before other kinds of brackets)
   1. No whitespace before the opening parenthesis of function calls, one space before the opening parenthesis of control structures (if, while etc.) (currently prevalent by far)
   2. No whitespace before any opening parenthesis
5. Braces
   1. Always one newline before the opening brace, never omit optional braces (variation of Allman) (currently prevalent by far)
   2. One newline before mandatory opening braces (e.g. function declarations), one space before optional opening braces (e.g. conditionals), never omit optional braces (OTBS)
   3. On rare occasions variations of the above with no whitespace before opening braces or omitted optional braces
6. Trailing whitespace
   1. No trailing whitespace anywhere (currently prevalent by far)
   2. Have indentation even on otherwise empty lines, otherwise no trailing whitespace
   3. Trailing whitespace? Who cares!
7. Aligning consecutive assignments
   1. Don’t align consecutive assignments (currently prevalent by far)
   2. Align consecutive assignments
8. Multi-line function calls / declarations
   1. First argument on initial line, each remaining argument on a line of its own and aligned with the first argument, closing parenthesis on same line as last argument (currently prevalent by far)
   2. First argument on initial line, each remaining argument on a line of its own and indented by one indent, closing parenthesis on same line as last argument
   3. First argument on initial line, each remaining argument as well as closing parenthesis on a line of its own and indented by one indent
   4. Every single argument on its own line and indented by one indent, closing parenthesis on its own line with same indentation as first line
   5. Arbitrary
9. Line length limit
   (For obvious reasons, I have no idea if there ever was a line length limit in Pencil’s code so I’m only including the “none” option here which is easy to spot)
   1. Who cares about line length! 428 characters on one line are nothing!
10. File encoding
    1. ASCII / UTF-8 w/o BOM (currently prevalent by far)
    2. UTF-8 w/ BOM (1 file)
11. Whitespace around operators
    1. One space before and after each operator (currently prevalent by far)
    2. No whitespace before or after each operator
    3. Arbitrary whitespace before and after each operator
12. Enum case
    1. SCREAMING_SNAKE_CASE
    2. PascalCase (currently prevalent)
13. Enum member case
    1. SCREAMING_SNAKE_CASE (currently prevalent by far)
    2. PascalCase
14. Member var names
    1. camelCase (currently prevalent for structs)
    2. m_camelCase (quite rare)
    3. mPascalCase (currently prevalent for classes)
15. Pass-by-reference in parameter lists
    (apparently no prevalent style here)
    1. type& param
    2. type &param
    3. type & param (quite rare, almost didn’t notice it because it looks so much like bitwise and)
16. Pointers
    (apparently no prevalent style here)
    1. type *identifier, type* when no identifier is given
    2. type* identifier
    3. type * identifier (quite rare)
17. Pointer pass-by-reference
    (this is currently not in master but I need it for my lav exporter so I’m including the choice that I made for discussion)
    1. type *&identifier
18. Aligning consecutive declarations
    1. Don’t align consecutive declarations (currently prevalent)
    2. Align consecutive declarations
19. Naming of non-boolean accessor functions
    1. get prefix (e.g. getColor(), currently prevalent)
    2. No prefix (e.g. color())
20. Naming of boolean accessor functions
    1. get prefix (e.g. getPlaying())
    2. No prefix (e.g. playing())
    3. is prefix (e.g. isPlaying(), currently prevalent)
    4. getIs prefix (e.g. getIsPlaying(), currently unused)
21. Naming of boolean mutator functions
    1. set prefix (e.g. setPlaying()`, currently prevalent)
    2. setIs prefix (e.g. setIsPlaying(), currently unused)
22. Naming of slots that are used exclusively for catching one specific signal
    1. on<SignalName> (e.g. onDurationChanged())
    2. No prefix (e.g. durationChanged()). Obviously this will have to be different from the signal name, or in a different class from the signal.
23. Documentation comment style
    1. Javadoc style

       /**
       ...
       **/

    2. Qt style

       /*!
       ...
       */

    3. Three slashes

       ///
       ///

    4. Two slashes and one exclamation mark

       //!
       //!

    5. Asterisk spam

       /********************************************//**
       ...
        ***********************************************/

    6. Slash spam

       /////////////////////////////////////////////////
       /// ...
       /////////////////////////////////////////////////

24. Intermediate asterisks
    Only effective if i, ii, or v is chosen in previous item (23).
    1. Include intermediate asterisks

       /**
        * ...
        */

    2. Skip intermediate asterisks

       /**
       ...
       */

25. Brief description format
    1. Always use \brief
    2. Autobrief, ends the brief description at the first dot (“.”) encountered. Use \brief if you want more than one sentence.
    3. A /// or //! comment before the main comment block
26. Member variable documentation comment style
    1. Regular style (22), before variable

       /** Description of var */
       int var;

    2. Regular style (22) except with <, after comment:

       int var; /**< Description of var */

27. Special command format
    1. @ prefix (Javadoc style, e.g. @param)
    2. \ prefix (e.g. \param)
28. Parameter descriptions
    1. @param command

       /**
        * @param[in] var String to print
        */
       void print(string var);

    2. Inline comment

       void print(string var /**< [in] String to print */);

For reference, there are a few things that do seem to be consistent throughout. For instance, line endings are always LF rather than CRLF, class case is always PascalCase, method case is always camelCase. I also didn’t include a few things that are almost universally consistent and should be a given, such as no whitespace before semicolons vs one space before semicolons.

If you think I made a mistake or forgot about / missed something that should be included, let me know. (Edit 2017-07-29: Added items suggested by @scribblemaniac)

Of course the prevalent styles might give a good direction, but I suggest we don’t take them as ultimate authority if we think there is a good reason to use another style, since someone (presumably me) is going to go over all the code to apply the style anyway, so we should take that opportunity.

Now, let the clash of beliefs begin. (But please do try to be flexible and keep it civil 🙂)