Coding Style

From Inkscape Wiki
Revision as of 11:13, 14 June 2004 by (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Inkscape Coding Style Discussion

The <a href="/doc/coding_style.php">official code style documentation</a> is on the main website.

This page is for discussing and working out changes and improvements to that document. When concensus is reached, the document can be updated in CVS int he inkscape_web module.

Tabs and Alignment

  • No tabs in files.
    • Tabs are evil.
    • By default many editors (and pagers as used for viewing diffs, and "diff -t") set tab stops to 8.
If files end up with mixed space & tab alignment (other than in a constrained way such as suggested below by mental), then it breaks formatting to use anything but 8 as one's editor's tab stop size.
    • A minor disadvantage of using spaces for indentation is that some text editors (not emacsen or vim) would require
using the space key a lot. On the other hand, code written in such an editor probably requires reformatting anyway.
    • Observing a rule of using tabs for structural indentation, and spaces for cosmetic (e.g. continuation) indentation, works
fine regardless of a particular user's tab stops. -- MenTaLguY
Somewhat contrived example (as seen with an 8-character tab stop):
          if (gromzalon) {
                    imagine_that_this_is_very_long(some, arguments,
                                                   go, here);
The breakdown:
<=Tab====>if (gromzalon) {
<=Tab====><=Tab====>imagine_that_this_is_very_long(some, arguments,
<=Tab====><=Tab====><=Spaces======================>go, here);
What this looks like with a tab stop of 3:
   if (gromzalon) {
      imagine_that_this_is_very_long(some, arguments,
                                     go, here);
-- MenTaLguY
(By the way, anyone submitting code with identifiers like "gromzalon" or "sprunklefrink" will be summarily shot.)
That spacing will often be undone [by editors themeslves, if not users]-- [JonCruz Jon C.]
<=Spaces======================>go, here

will get mangled by most editors. Often like this:

<=Tab=Tab=Tab=Tab=Spaces=>go, here

emacs21 mode

The following should get emacs users started. Put the following in your ~/.emacs file and load it:

     (setq c-basic-offset 4
         c-offsets-alist '((innamespace . -2)(substatement-open 0))
         c-brace-offset 0)

Some additional emacs21 notes:

  • .h files load C mode, not C++ mode. Hit M-x and type c++-mode and it loads c++-mode.
  • C-M-\ indents a buffer and converts all tabs to whitespace.
    • Can anyone give a specification for common editors or astyle/indent to give this behaviour, or suggest a script to check where this hasn't been done?
Without such automation, this approach won't be used by many developers.
    • Suggesting that people change their tab stop size is only practical if all source code uses spaces & tabs the same way.
This may be possible with mode lines if all Inkscape developers stick to editors with appropriate modeline support (emacsen, vim/gvim; anything else?).
Do any popular Windows/MacOS editors (other than the above) support mode lines?
What about KDevelop/anjuta/other IDE's on Un*x?
It's fairly easy to define this behavior for Emacs and VIM. Having it explicit might be enough.
It's possible to add checkin scripts to CVS to warn/prevent checkins with tabs, etc.
Something else to consider is developer culture -- _most_ of our developers at this point will likely be coming from GNU, GNOME or Linux backgrounds, where using 8-column tabs for indention is the norm (and indeed part of the coding standards).
  • Objective studies have found that indentions between 2 and 6 columns are optimal.
Reference: [ProgramIndentation Miara, J. R., J. A. Musselman, J. A. Navarro, and B. Shneiderman. Program

Indentation and Comprehensibility. Comm. ACM 26, 11 (Nov. 1983), 861-867.]

Brace Placement

Arguments against "disco"/compact braces:

  • Make it hard to match braces visually.
Partial counter-argument: emacsen & vim each have brace-locating commands. (Emacsen: C-M-u, C-M-n, C-M-p, C-M-d (up/next/prev/down); vim: `[ {', `] }'.)
  • The brace closes a block, not an if "statement".
However, the block is intimately related to the if/for/while in ways that a normal block is not.