camel_casing.png

Motivation

It is important to have a unified code for a number of reasons. The following quote lists some of them:
1.1 Why Have Code Conventions

Code conventions are important to programmers for a number of reasons:

    * 80% of the lifetime cost of a piece of software goes to maintenance.
    * Hardly any software is maintained for its whole life by the original author.
    * Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly.
    * If you ship your source code as a product, you need to make sure it is as well packaged and clean as any other product you create. 

Proposed Code Conventions

This XML file contains the code conventions in a form that is loadable into the Eclipse IDE.

The following files shows the code convention for the argos control software:

Name of header file is SwingArm.h (C++ header files have extension '.h'):
#ifndef ARGOS_CHAOSDEVICE_SWINGARM_H
#define ARGOS_CHAOSDEVICE_SWINGARM_H

/**
 * @note alphabetical order of include files if possible.
 */
#include "bar.h"
#include "foo.h"
#include "muh.h"
#include "SomeBaseClass.h"

namespace argos { namespace chaosdevice {


/**
 * @brief This class demonstrates the coding standard of
 *        the argos control software.
 */
class SwingArm : public SomeBaseClass 
{
public:
    typedef int Foo;

    SwingArm(int id);

    int getId() const;
    int bar(int arg);
    int foo();
    void methodWithManyArgments(SomeBaseClass* a1, SomeBaseClass& a2,
            SomeBaseClass a3, SomeBaseClass a4);

private:
    int id_;
};

enum Example 
{
    CANCELLED= 1,
    RUNNING=   2,
    WAITING=   3,
    FINISHED=  4
};

}

}

#endif

Implementation file name is SwingArm.cpp (C++ implementation files have extensions '.cpp'):
#include "SwingArm.h"

#include "otherHeaders.h"

namespace argos { namespace chaosdevice {

SwingArm::SwingArm(int id) : 
    id_(id)
{
}

int SwingArm::getId() const
{
    return id_;        
}

int SwingArm::bar(int arg)
{
    const int muh= 7;

    if (42 == id_)
    {
        return 1;                   
    } 
    else if (arg == id_)
    {
        return 3;
    } 
    else 
    {
        return muh;
    }
}

int SwingArm::foo()
{
    switch (id_) 
    {
        case 0:
            ++id_;
            break;
        case 1:
            --id_;
            /* FALL THROUGH */
        default: 
        {
            id_+= id_;
            break;
        }
    }

    int k[3];
    while (0 < id_) 
    {
        k[id_ % 3]= bar(--id_);
    }

    return id_;
}

void SwingArm::methodWithManyArgments(SomeBaseClass* a1, SomeBaseClass& a2,
        SomeBaseClass a3, SomeBaseClass a4)
{
    const SomeBaseClass* b= a1;
    SomeBaseClass& ref= a3;
}

}

}

Additional Code Format Conventions

  1. Annotate threadsafe functions, methods and classes: /** @note thread-safe */
  2. Argos software uses medial capitals for identifiers.

Python Code

Python code for Argos ICS is based on the style guide for the Python standard library. The file chaos_device.py demonstrates the Argos ICS code conventions:
"""A Device for controlling chaos

It is important to prevent chaos.  Therefore,  Argos has code conventions.
"""

import os
import sys

class ChaosDevice:
    """Device for controlling chaos.

    This class abstracts from the property tree of the chaos basda device.
    """

    def __init__(self, path):
   self._path= path

    def goToTheMatrix(self):
   if self._path.startswith("a"):
            os.chdir("b")
   elif "foo" == self._path:
       os.chdir(sys.path[1])
   else:
       os.remove(self._path)

        for i in xrange(0, 3):
       self._say(i)
   
   j= 5
   k= 3
   l= []
   while k < 9:
       l.append(j + k)
       k= k + 1
   
    def _say(self, x):
        """A private method.

   A leading underscore denotes private methods.
   """
   print(x)

Encoding of Acronyms

The goal of encoding of acronyms is readability:
class AoSquirrel(object):


    def __init__(self):
        self._httpProxy= None
        self._lgswCtrlClient= None


    def setHttpProxy(self, httpProxy):
        pass


    def setLgswControllerClient(self, lgswCtrlClient):
        pass


    def aoReconstructor(self):
        return None


    def setAoReconstructor(self, aoReconstructor):
        pass


    def setAArbConfiguration(self, config):
        pass


    def setTipTiltDevice(self, device):
        pass

Rules

Here are some important rules for the Argos ICS:
  1. Line indentation is 4 spaces.
  2. Tabs are forbidden!
  3. Maximum line length is 79 characters.
  4. Comments should be complete sentences.
  5. Python coders from non-English speaking countries: please write your comments in English, unless you are 120% sure that the code will never be read by people who don't speak your language.
  6. Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability.
  7. Class names use the CapWords (medial capitals) convention.

Eclipse Support

The Python plugin PyDev for Eclipse has a tool for checking source code on conformity with PEP8 standard. Argos can reuse most of the functionality of this tool except that:
  1. Restriction of only one blank line between class methods (E303)
  2. Implicit indication of source and destination during assignment operation (E225)
Thus, the following argument for pep8.py has to be added:
--ignore=E225,E303,E251,E402

Python Version

Today (2011-08-31), the Python major versions in use are 2.7 and 3.2. Python 3 lacks backward compatibility to Python 2. The goal of Python 3 was the clean up of the old language (e.g. all strings are unicode in Python 3). The Python developers plan to maintain Python 2 for a long time because many Python packages requires Python 2.

The LBT runs the CentOS operating system which is notorious for its old software packages. Therefore, it is unlikely that this OS will provide up-to-date software packages for Python 3 in the future.

As long as popular Python packages depends on Python 2, the Argos ICS should use Python in version 2. At the moment, there is no need for the Argos ICS to use Python 3 language features.

Interesting Links:
  1. Should I use Python 2 or Python 3 for my development activity?
  2. Programm text changes between python 2 and python 3
  3. Future of Python 2

Problems of Python

Python is a scripting language. Like every other language, Python has some limitations which hinders its usage for particular tasks.

The following list should make the Argos team aware of the Python problems:
  1. Good overview of Python Problems
  2. Python is slow but maybe fast enough for some tasks.
  3. Python lacks compile-time type checking. In order to avoid unpleasent surprises, unit tests with a high test coverage are necessary.
  4. Indentation with whitespaces define statement blocks.
Topic revision: r4 - 15 Aug 2018, MatthieuBec
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback