Gromacs

Code Formatting

    Indentation

    In order to properly comprehend code indentation is crucial. We recommend the following layout for all new code:

    • 4 spaces indentation for each level. If you are running out of screen space you should use this fancy new feature called "function"  ;-)
    • Do not use tabs, spaces only - most editors can be set to generate spaces when you press the tab key! Tabs are inconvenient, e.g, when doing git diff, because the indendation may appear very different from what it is in your editor.
    • Avoid trailing whitespace. It's invisible in most editors by default, but can cause confusion when you unintentionally remove or add it, because that still counts as a change for git on that line. git diff with colors shows all trailing whitespace very clearly.

    This can be enforced by writing this comment as the first line in your source file (when using emacs).

    /* -*- mode: c; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; c-file-style: "stroustrup"; -*- */ 

    Then, after you inserted this, you return to the top of the file, press Ctrl-space, go to the bottom of the file and type Esc-x indent-region. Your source code file is now indented correctly according to GROMACS standards. It may be necessary to close and re-open the file, since emacs reads this magic comment only upon file opening.

    We now prefer to automate formatting through editor configuration, because editor choice should be the hands of the programmer.

    Indentation guide for emacs

    Insert the following in your .emacs file (based on content from stackoverflow):

    (defun gromacs-c-mode-common-hook ()
     ;; GROMACS customizations for c-mode
    
     (c-set-offset 'substatement-open 0)
     (c-set-offset 'innamespace 0)
     ;; other customizations can go here
                                                                 
     (setq c++-tab-always-indent t)
     (setq c-basic-offset 4)                  ;; Default is 2
     (setq c-indent-level 4)                  ;; Default is 2
     (setq c-file-style "stroustrup")
     
     (setq tab-stop-list '(4 8 12 16 20 24 28 32 36 40 44 48 52 56 60))
     (setq tab-width 4)
     (setq indent-tabs-mode nil)  ; use tabs if t
     )
     
    (add-hook 'c-mode-common-hook 'gromacs-c-mode-common-hook)
    
    (defun gromacs-c++-mode-common-hook ()
     ;; GROMACS customizations for c++-moe
    
     (c++-set-offset 'substatement-open 0)
     (c++-set-offset 'innamespace 0)
     ;; other customizations can go here
    
     (setq c++-tab-always-indent t)
     (setq c++-basic-offset 4)                  ;; Default is 2
     (setq c++-indent-level 4)                  ;; Default is 2
     (setq c++-file-style "stroustrup")
     
     (setq tab-stop-list '(4 8 12 16 20 24 28 32 36 40 44 48 52 56 60))
     (setq tab-width 4)
     (setq indent-tabs-mode nil)  ; use tabs if t
     )
     
    (add-hook 'c++-mode-common-hook 'gromacs-c++-mode-common-hook)
    
    
    

    Open a new emacs session so that this gets read. Now all your edits will conform to GROMACS style expectations.

    To re-format existing code, open a file and position the pointer at the top of the file. Use Ctrl-x h to mark the whole file. Then Ctrl-Meta-\ will run indent-region to enforce the style that was read from your .emacs earlier. (Meta is often bound to the Alt key, or perhaps Esc.)

    To re-format lots of files, save the following as gromacs-format-function.el:

    (defun gromacs-format-function ()
       "Format the whole buffer."
       (c-set-offset 'substatement-open 0)
       
       (setq c-tab-always-indent t)
       (setq c-basic-offset 4)                  ;; Default is 2
       (setq c-indent-level 4)                  ;; Default is 2
       (c-set-style "stroustrup")
       
       (setq indent-tabs-mode nil)
       (indent-region (point-min) (point-max) nil)
       (delete-trailing-whitespace)
       (save-buffer)
    )
    
    

    then use the following bash command:

    for file in your-glob.c; do emacs -batch $file -l gromacs-format-function.el -f gromacs-format-function; done
    

    Indentation guide for eclipse/cdt

    Use this profile.

    Block Structure

    In order to make the source code readable always use braces around blocks, and put braces on the next line, even if it is unambiguous. Use

    if (foo) 
    {
        blah();
    }
    else 
    {
        bleh();
    }
    
    for (i=0; (i<imax); i++)
    {
        printf("Foo %d\n",i);
    }

    rather than:

    if (foo)
      blah();
    else
      bleh();
    for(i=0;i<imax;i++) 
      printf("Foo %d\n",i)

    Note that there is an empty line between the two logical blocks (if statement and for loop)

    Try to add a comment before a loop or conditional statement to tell *why* you are doing something, not what you are doing. Most users hacking the code know that i++ means that you incrementing i, but why are you incrementing it?

    Spaces are good - that's what the space-bar on your keyboard is so large :-) Personally I feel that e.g. using parentheses around the i<imax test in the loop above is unnecessary, but to make a point I won't alter it: if in doubt, use spaces or parentheses! --Lindahl 21:14, 27 February 2009 (CET)

    Page last modified 22:18, 19 Jun 2014 by rolandschulz