fldigi Wiki

Ham Radio Digital Modem Application

Brought to you by: dave-w1hkj, mdblack98, sb42

dev-docs Log in to Edit

Developers

These documents are located on the https://www.w1hkj.org site, docs directory

This file contains coding guidelines for NBEMS application source. You should follow them if you want to contribute to NBEMS.

General rules

The recommended developers editor is Geany. It is available for every target operating system. Set the editor preferences to use a fixed font. Set the tab interval to 4 spaces, use tabs for indentation. Set the end-of-line to use the Unix standard of LF and not CR-LF which is commonly used by Windows developers.

Language

The project language is English. All comments, variable names, class names, commit messages and so on, must be in English.

Version Control

Version control is maintained using git. The remote repository for each application is at Source Forge.

Style, indentation and braces

Indentation

Use TABS (ASCII character #9) and not SPACES. This allow everyone to set tab width to the preferred settings of 4 spaces / tab.

Brace position

Open braces should always be at the end of the line of the statement that begins the block. Contents of the brace should be indented by 1 tab.

 if (expr) {
    do_something();
    do_another_thing();
 } else {
    do_something_else();
 }

A function with few arguments:

bool header::hasField(const string& fieldName) const {
...
}

A function with more arguments:

void header::parseImpl(
    const parsingContext& ctx,
    const string& buffer,
    const size_t position,
    const size_t end,
    size_t* newPosition
) {
         ...
}

"switch" statement

switch (expr) {
    case 0:
        something;
        break;
    case 1:
        something_else;
        break;
    case 2: {
        int var = 42;
        another_thing;
        break;
    }
    default:
        something;
}

Single instruction

Don't omit braces around simple single-statement body:

   if (...) {
      something;
   }

and not:

if (...)
    something;

Line length

If possible, each line of text should not exceed 80 characters, except if manual line wrapping breaks code clarity.

Exception: if a comment line contains an example command or a literal URL longer than 100 characters, that line may be longer than 100 characters for ease of cut and paste.

Spaces and parentheses

Put spaces around operators: =, >, <, !=, +, -, /, *, ^, %, ||, &&, &, |:

x = (a * (b + (c - d)))

Do not put spaces around parentheses.

if ((a == b) || (c == d))

Do not put spaces around "->", or "."

object->method()
object.method()

Do not put spaces inside brackets:

x = array[index]     and _NOT_:    x = array[ index ]

Do not use space between a function name and parenthesis. No extra spaces between parameters and arguments, just after commas:

method(arg1, arg2, ...)

Do use a single space before flow control statements:

while (x == y)     and _NOT_:    while(x==y)

End-of-line character

Configure your editor to use "\n" (UNIX convention) for end-of-line sequence, and not "\r\n" (Windows), nor "\n\r", nor any other combination.

Short functions

To the extent that it is feasible, functions should be kept small and focused. It is, however, recognized that long functions are sometimes appropriate, so no hard limit is placed on method length. If a function exceeds 40 lines or so, think about whether it can be broken up without harming the structure of the program.

Limit Variable Scope

The scope of local variables should be kept to a minimum. By doing so, you increase the readability and maintainability of your code and reduce the likelihood of error. Each variable should be declared in the innermost block that encloses all uses of the variable.

Local variables should be declared at the point they are first used. Nearly every local variable declaration should contain an initializer. If you don't yet have enough information to initialize a variable sensibly, you should postpone the declaration until you do.

Naming conventions

Classes

Classes names are in lower-case. However, each word should start with an upper-case letter, or be separated with an underscore. Examples:

class object {
...
};
class exampleClass {
...
};
class anotherExampleClass {
...
};
class example_class {
...
};
class another_example_class {
...
};

Variables/parameters/member variables

Variable names should be enough explicit so that someone reading the code can instantly understand what the variable contains and is used for.

Variables names are in lower-case.

DO NOT use Hungarian notation.

Examples: "address", "recipientMailbox", "recipient_mailbox" ...

Avoid variable names with less than 5 characters, except for loop indices and iterators.

NOTE: variable names like "it", "jt" and so on are commonly used when iterating over STL containers.

Member variables

Use a prefix for class members: "m_" for normal class members, and "sm_" for static members, if they are not public.

Examples: "m_mailboxList", "sm_instance"...

Files

Use ".h" for header files, and ".cxx" for implementation files.

If possible, files should be named exactly like the class they define. For example, class "mailboxList" should be declared in "mailboxList.h" and
implemented in "mailboxList.cxx".

Implementation files are placed in src/implementation-directory

Header files are placed either in ~~~src/include/~~~, or in ~~src/implementation-directory/include/~~~. The latter if the headers are only used by the implementation.

Namespaces

Namespaces are named exactly like variables.

Constants

Constants are ALL_CAPS_WITH_UNDERSCORES.

#define PI_DIV_2 (M_PI / 2.0)

Comments

The ~~~//~~~ (two slashes) style of comment tags should be used in most situations. Where ever possible, place comments above the code instead of beside it.

Comments can be placed at the end of a line when one or more spaces follow.
Tabs should NOT be used to indent at the end of a line:

class myClass {
 private:
    int m_member1;         // first member
    int m_secondMember;    // second member
};

Note about special comment blocks: Doxygen is used to generate documentation from annotated C++ sources, so be sure to use available markings to annotate the purpose of the functions/classes and the meaning of the parameters.

Doxygen comment are delineated with three slashes ~~~///~~~ vice two.

Miscellaneous

No code should be put in header files, only declarations (except for templates and inline functions).
Try to avoid public member variables. Write accessors instead (get/set).
Do NOT use 'using namespace' (and especially not in header files). All namespaces should be explicitely named. (notable exception is for std, "using namespace std".
Use the 'get' and 'set' prefix for accessors:

Variable:    m_foo
Get method:  getFoo()
Set method:  setFoo()

No more than one class per file (except for inner classes).
Put the #include for the class's header file first in the implementation file.
Put the copyright header at the top of each file.
Write "unique inclusion #ifdef's" for header files:

#ifndef N1_N2_FILENAME_HPP_INCLUDED
#define N1_N2_FILENAME_HPP_INCLUDED
...
#endif // N1_N2_FILENAME_HPP_INCLUDED

where N1 is the top-level namespace, N2 the sub-namespace, and so on. For example, class ~~~vmime::utility::stringUtils~~~ uses the following

#ifdef name: VMIME_UTILITY_STRINGUTILS_HPP_INCLUDED.

Copyright header

// =====================================================================
//
// file_name.cxx
//
// Authors:
//
// Copyright (C) 2019, Dave Freese, W1HKJ
//
// This is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 3 of the License, or
// (at your option) any later version.
//
// This software is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.
//
// =====================================================================