subsurface/CodingStyle

Coding Style
============

Here are some of the basics that we are trying to enforce for our coding style
and conventions. The existing code (as of the commit that adds these lines) is
not yet fully consistent to these rules, but following these rules will make
sure that no one yells at you about your patches.

We have a script that can be used to reformat code to be reasonably close
to these rules; it's in scripts/whitespace.pl - this script requires
clang-format to be installed (which sadly isn't installed by default on
any of our platforms; even on Mac where clang is the default compiler).

At the end of this file are some ideas for your .emacs file (if that's
your editor of choice) as well as for QtCreator. If you have settings for
other editors that implement this coding style, please add them here.

Basic rules
===========

- all indentation is tabs (set to 8 char) with the exception of
  continuation lines that are aligned with tabs and then spaces

- all keywords followed by a '(' have a space in between

	if (condition)

	for (i = 0; i < 5; i++)

- function calls do NOT have a space between their name and argument

	i = some_function(argument);

- usually there is no space on the inside of parenthesis (see examples
  above)

- function / method implementations have their opening curly braces in
  column 1

- all other opening curly braces follow at the end of the line, with a
  space separating them:

	if (condition) {
		dosomething();
		dosomethingelse();
	}

- both sides of an if / else clause either use or do not use curly braces:

	if (condition)
		i = 4;
	else
		j = 6;

	if (condition) {
		i = 6;
	} else {
		i = 4;
		j = 6;
	}

- use space to make visual separation easier

	a = b + 3 + e / 4;

- continuation lines have the operator / comma at the end

	if (very_long_condition_1 ||
	    condition_2)

	b = a + (c + d +
		 f + z);

- in a C++ constructor initialization list, the colon is on the same line and
  continuation lines are aligned as the rule above:

	ClassName::ClassName() : x(1),
		y(2),
		z(3)
	{
	}

- unfortunate inconsistency:
  -- C code usually uses underscores to structure names

	variable_in_C

  -- C++ code usually uses camelCase

	variableInCPlusPlus

  where the two meet, use your best judgment and go for best consistency
  (i.e., where does the variable "originate")

- switch statements with blocks are a little bit special (to avoid indenting
  too far)

	switch (foo) {
	case FIRST:
		whatever();
		break;
	case SECOND: {
		int i;
		for (i = 0; i < 5; i++)
			do_something(i);
	}
	}

Coding conventions
==================

- variable declarations
  in C code we really like them to be at the beginning of a code block,
  not interspersed in the middle.
  in C++ we are a bit less strict about this - but still, try not to go
  crazy.

- text strings
  The default language of subsurface is US English so please use US English
  spelling and terminology.
  Where at all possible strings should be passed to the tr() function to enable
  translation into other languages.

  -- like this
	QString msgTitle = tr("Submit user survey.");

  -- rather than
	QString msgTitle = "Submit user survey.";


- UI text style
  These guidelines are designed to ensure consistency in presentation within
  Subsurface.
  Only the first word of multi-word text strings should be capitalized unless
  a word would normally be capitalized mid-sentence, like Africa. This applies
  to all UI text including menus, menu items, tool-tips, button text and label
  text etc. e.g. "Check for updates" rather than "Check for Updates".
  We also capitalize Subsurface (NOTE: not SubSurface) when referring to the
  application itself.
  Abbreviations should end with a period, e.g. "temp." not "temp" for
  temperature
  Numerals in chemical formulae should use subscript characters e.g. O₂ not O2
  Partial pressures in Subsurface are, by convention, abbreviated with a single
  "p" rather than 2, as in pO₂ not ppO₂
  Where more than one term exists for something, please choose the one already
  in use within Subsurface e.g. Cylinder vs. Tank.


- string manipulation

 -- user interface
    In UI part of the code use of QString methods is preferred, see this pretty
    good guide in QString documentation:
    http://doc.qt.io/qt-5/qstring.html#manipulating-string-data

 -- core components
    In the core part of the code, C-string should be used.
    C-string manipulation is not always straightforward specifically when
    it comes to memory allocation, a set of helper functions has been developed
    to help with this. Documentation and usage examples can be found in
    core/membuffer.h file:
    https://github.com/Subsurface-divelog/subsurface/blob/master/core/membuffer.h

Sample Settings
===============

Emacs
-----

These lines in your .emacs file should get you fairly close when it comes
to indentation - many of the other rules you have to follow manually

;; indentation
(defun c-lineup-arglist-tabs-only (ignored)
  "Line up argument lists by tabs, not spaces"
  (let* ((anchor (c-langelem-pos c-syntactic-element))
         (column (c-langelem-2nd-pos c-syntactic-element))
         (offset (- (1+ column) anchor))
         (steps (floor offset c-basic-offset)))
    (* (max steps 1)
       c-basic-offset)))

(add-hook 'c-mode-common-hook
          (lambda ()
            ;; Add kernel style
            (c-add-style
             "linux-tabs-only"
             '("linux" (c-offsets-alist
                        (arglist-cont-nonempty
                         c-lineup-gcc-asm-reg
                         c-lineup-arglist-tabs-only))))))

(add-hook 'c-mode-hook
          (lambda ()
            (let ((filename (buffer-file-name)))
              ;; Enable kernel mode for the appropriate files
                (setq indent-tabs-mode t)
                (c-set-style "linux-tabs-only"))))

(add-hook 'c++-mode-hook
          (lambda ()
            (let ((filename (buffer-file-name)))
              ;; Enable kernel mode for the appropriate files
                (setq indent-tabs-mode t)
                (c-set-style "linux-tabs-only"))))


QtCreator
---------

These settings seem to get indentation right in QtCreator. Making TAB
always adjust indent makes it hard to add hard tabs before '\' when
creating continuing lines. Copying a tab with your mouse / ctrl-C and
inserting it with ctrl-V seems to work around that problem (use Command
instead of ctrl on your Mac)
Save this XML code below to a file, open Preferences (or Tools->Options)
in QtCreator, pick C++ in the left column and then click on Import...
to open the file you just created. Now you should have a "Subsurface"
style that you can select which should work well for our coding style.


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE QtCreatorCodeStyle>
<!-- Written by QtCreator 3.0.0, 2014-02-27T07:52:57. -->
<qtcreator>
 <data>
  <variable>CodeStyleData</variable>
  <valuemap type="QVariantMap">
   <value type="bool" key="AlignAssignments">false</value>
   <value type="bool" key="AutoSpacesForTabs">false</value>
   <value type="bool" key="BindStarToIdentifier">true</value>
   <value type="bool" key="BindStarToLeftSpecifier">false</value>
   <value type="bool" key="BindStarToRightSpecifier">false</value>
   <value type="bool" key="BindStarToTypeName">false</value>
   <value type="bool" key="ExtraPaddingForConditionsIfConfusingAlign">false</value>
   <value type="bool" key="IndentAccessSpecifiers">false</value>
   <value type="bool" key="IndentBlockBody">true</value>
   <value type="bool" key="IndentBlockBraces">false</value>
   <value type="bool" key="IndentBlocksRelativeToSwitchLabels">false</value>
   <value type="bool" key="IndentClassBraces">false</value>
   <value type="bool" key="IndentControlFlowRelativeToSwitchLabels">true</value>
   <value type="bool" key="IndentDeclarationsRelativeToAccessSpecifiers">true</value>
   <value type="bool" key="IndentEnumBraces">false</value>
   <value type="bool" key="IndentFunctionBody">true</value>
   <value type="bool" key="IndentFunctionBraces">false</value>
   <value type="bool" key="IndentNamespaceBody">false</value>
   <value type="bool" key="IndentNamespaceBraces">false</value>
   <value type="int" key="IndentSize">8</value>
   <value type="bool" key="IndentStatementsRelativeToSwitchLabels">true</value>
   <value type="bool" key="IndentSwitchLabels">false</value>
   <value type="int" key="PaddingMode">2</value>
   <value type="bool" key="SpacesForTabs">false</value>
   <value type="int" key="TabSize">8</value>
  </valuemap>
 </data>
 <data>
  <variable>DisplayName</variable>
  <value type="QString">Subsurface</value>
 </data>
</qtcreator>


Vim
---------

As everybody knows vim is a way better editor than emacs and thus needs to be
in this file too. Put this into your .vimrc and this should produce something
close to our coding standards.

" Subsurface coding style
filetype plugin indent on
filetype detect
set cindent tabstop=8 shiftwidth=8 cinoptions=l1,:0,(0,g0
" TODO: extern "C" gets indented

" And some sane defaults, optional, but quite nice
set nocompatible
syntax on
colorscheme default
set hls
set is

" The default blue is just impossible to see on a black terminal
highlight Comment ctermfg=Brown

" clearly point out when someone have trailing spaces
highlight ExtraWhitespace ctermbg=red guibg=red

" Show trailing whitespace and spaces before a tab:
match ExtraWhitespace /\s\+$\| \+\ze\t/