CodeStyleGuide - adda-team/adda GitHub Wiki

This style description aims to help different parts of ADDA look similar. Most of the below "rules" are just conventions, each being one of several equivalent options. Still, adhering to one of such options seems beneficial. This style is based on the current state of the code, which is a result of hard-to-track evolution. Moreover, it may change in the future. The style is rather short, so it is recommended to use existing files as examples.

C sources and headers

File structure

Each source file has the following components:

  • Starting comment: 
    /* <short description, possibly several lines>
 *
 * Copyright (C) ADDA contributors
 * <standard copyright statement>
 */
  • #include directives. Start with const.h (needed for all source files), followed by other project headers, and then system headers.
  • File-scope variable declarations. First semi-global variables are defined (used in this and one more source file), then - local variables (declared as static).
  • External function declarations (for some specific functions which do not have corresponding header files).
  • Function definitions, each preceded by a delimiter //=====...===== and with descriptive comment before opening {.

Header files follow the same structure (where applicable) and have everything except the starting comment enclosed in guarding construct:

#ifndef __<name>_h
#define __<name>_h
...
#endif // __<name>_h

Format

  • Indentation is done using tabs only. Tab size = 4. Spaces can only be used in (part of) indentation of multi-line expressions (see below). Function bodies and all blocks are indented. Preprocessor directives are also indented inside conditionals, but # is kept in the line beginning. 
    #ifdef AAA
#   include "a.h"
#endif
  • Opening brace { is on the next line for a function body, and on the same line for everything else. 
    void foo(void)
{
    if (i==1) {
        i++;
    }
}
  • White spaces are added around bracketed control statements and before opening {, but neither inside brackets nor between function arguments. Spaces in expressions can be used when visually appropriate. 
    if (a==b) {
    x = (fun(a,b)+y)*z + (fun(b,c)+z)*y; 
}
  • else is placed on a new line, while (after do) - not. Simple (one-statement) "then" statements (after if, while, for, etc.) are placed on the same line and not enclosed in {} (when this is semantically equivalent). 
    if (i==0) return;
else if (j==0) return;
else for (i=0;i<j;i++) printf("%d",i);
  • Maximum line width = 120. Wrapped part is indented by one extra tab (the third and further lines are indented the same as the second one). Wrapping can be done at (strategic) points between larger constructs if that doesn't increase the total number of lines. 
    if (............................)
    printf(a,b,..................................);
  • Multi-line mathematical expressions can be aligned at operands. For that the wrapped part is indented by the same amount of tabs as the first line of the expression and further adjusted by spaces. 
    x = a*(b+c) + b*(a+c)
  + c*(a+b);
  • One-line comments are made with //. If made on a line with the code, this comment is separated by space from the code. Also, space is inserted between // and comment text. All multi-lines comments should be made with /*...*/. More specifically, 
    /* line 1
 * line 2
 */

Most of the above format settings are available as configuration file to be imported into Eclipse CDT, see details.

Makefiles and other (shell) scripts

  • Makefiles contain starting comment similar to source files.
  • All comments start with "# " (note the space).
  • Maximum line width = 120, wrapped by \.
  • Indentation is done with two spaces (except for action part of the Makefiles where tabs are required).
  • then is kept on the same line with if. 
    if [ $# -ne 1 ]; then
  exit 1
fi

Wiki pages (Markdown)

Basics

  • Follow the standard guides, e.g., this and this, and/or use visual editors.
  • Indentation is done with two spaces.
  • No manual line wrapping is used.
  • Inline-code format `...` is not used for code names, like ADDA and FFTW3 (since they look ugly at GitHub, especially when appear often). But this format is used for command lines (tools).
  • Any two paragraphs are separated by two lines except the elements in a list. However, the code block separators ``` can count as such blank line.
  • Other wiki pages are linked by relative links without the extension .md, such as [Visible text](WikiName).
  • Similarly, relative links are used for issues, commits (truncate hash to 7 symbols), source files, and releases. 
    [#123](../issues/123)
[8fbc055](../commit/8fbc055)
[src/const.h](../blob/master/src/const.h)
[ADDA v1.2](../releases/tag/v1.2)
  • Note that these relative links do not appear properly in the preview (when editing wikis online). The latter would add /<WikiName> in the middle that would disappear after the edit is finalized.
  • To refer to a section inside the wiki page, use WikiName#heading (the link to a specific heading can be found by hovering the mouse to the left of it). Do not insert / before # - the corresponding link will work, but all relative links inside this page - will not.
  • New wiki page should also be specified in a proper section of the sidebar.
  • Publications in the text or in the reference lists are formatted using the same format, see ,e.g., Publications and Comparison with other codes. We also provide citation style in open format CSL.

Advanced

  • If the page is longer than one screen and contains headings, it typically contains a table of contents (TOC). Unfortunately, Markdown does not support automatic TOC generation. However, we provide a special script update-toc for that (read carefully the comments inside). Use it both for adding new pages and for editing existing one (if the headings are added or modified).
  • Bulk editing of wiki pages is best done locally after cloning the separate Git repository adda.wiki.git (see below the sidebar to the right). This way you will also have direct access to the script update-toc.
  • Git is also needed to add auxiliary files (referred to from the wiki pages). For that use existing directory structure, i.e. put images into img/ and other files into files/.
  • For the sidebar (only) the focus is strictly on the final look (to fit a lot of information into a limited space), even at the expense of readability of the plain text. For instance, line breaks (trailing two spaces) are used extensively.

Markdown usage in issues

The guidelines are the same, but all those details are redundant for short descriptions/comments. Issues and commits are auto-linked, while the relative links are used for wikis, source files, and releases.

#123
8fbc055
[wiki page](../wiki/WikiName)
[src/const.h](../blob/master/src/const.h)
[ADDA v1.2](../releases/tag/v1.2)

Markdown usage in release notes

This is relevant for release notes, found at GitHub-powered releases. The guidelines are the same as for issues, but one extra ../ is used in relative links to wikis, source files, and other releases.

#123
8fbc055
[wiki page](../../wiki/WikiName)
[src/const.h](../../blob/master/src/const.h)
[ADDA 1.2](../../releases/tag/v1.2)

Markdown files in the main repository

This is relevant for README.md in the repository root and other folders (i.e. not wikis). The same general guidelines apply except for links. Relative links are used for other source files, but absolute - for issues, commits, wikis, and releases.

[manual](doc/manual.pdf)
[#123](https://github.com/adda-team/adda/issues/123)
[8fbc055](../commit/8fbc055)
[wiki page](https://github.com/adda-team/adda/wiki/WikiName)
[ADDA 1.2](https://github.com/adda-team/releases/tag/v1.2)

The reason for that is the wide use of forks and local clones in Git. Those copy only the source files and neither issues nor wikis (tags are also copied, but not release notes). Thus, it is natural for all forked files to refer to the issues, wikis, and releases of the parent (upstream) repository. Commits are, in principle, forked, but absolute links will help for local clones. By contrast, wikis, issues, and release notes are typically not forked/cloned, thus relative links from them will always point to the same locations in the main repository.

Tools for Windows

Apart from editing wiki pages online at GitHub, there exist a wide variety of tools to do it efficiently offline. In the following one toolchain for Windows is described. It is especially handy for bulk editing, e.g., search-and-replace in all wikis.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️