Debian coding style?
Query, is there actually a coding style guideline for debian stuph?
Basically I'm with the Corel Linux group and this is what the Corel
Linux Coding guidelines say... (follows). A few note-worthy ones are:
- tabs: 2 spaces
- curly braces alway on next line
ie if (...)
{
}
else
{
}
- hungarian notation
Will the Debian community be excrusiatingly unhappy with this?
---------------------------------------------------------------
These coding guidelines are meant to ensure that other people working on
your project can read and clearly understand your code. It is also hoped
that following these guidelines will lead to code which is less prone to
bugs, both by the initial author and later by those who maintain it. All new
code written must follow these guidelines, including new functions added to
existing sources files. Modifications made to existing code may follow the
coding style used by the original author in order to maintain readability.
If you disagree with or don't understand the reasoning behind any of the
following guidelines, you are encouraged to discuss your concerns with your
project leader.
* Compiling: all code must compile clean at warning level 3 with warnings
as errors.
2. Testing: all code must be compilable, tested, and DIFF'ed before being
checked into source safe. No code should ever be checked in if it will break
functionality in another part of the program, or if it will break the build.
All code must be tested by the developer before being checked in. This
includes walking through the code using a debugger and forcing error
conditions to make sure that all code paths have been tested. Remember that
the person who is most qualified to test any piece of code is the person who
wrote it.
3. Tabs should be set to 2, and they should be kept as tabs, no spaces
please.
4. Code width: The complete line of code should be visible without having to
scroll horizontally - i.e. it should normally not pass the 78th column.
5. Naming conventions:
a) Class names always start with upper-case 'C', followed by an upper-case
letter, followed by mixed upper/lower case and must always take the form of
a descriptive noun.
eg. class CPhoneBookEntry
b) Method/function names always start with upper-case followed by mixed
upper/lower case and must always take the form of a descriptive verb or
action.
eg. void CPhoneBookEntry::GetUserName();
c) Variable names must use hungarian notation (see below) followed by
upper-case followed with mixed upper/lower case and must always take the
form of a descriptive noun. Variables which are members of a class must have
m_ prepended to the name.
eg. int nUsageCount;
char* m_pstrUserName;
Hungarian Notation:
m_ member variable
ch char
n int, unsigned int
s short, unsigned short
l long
u unsigned
b bool
d double
f float
a array of
str, sz any string (str preferred for new code)
e enumerated type
id integer ID of a control, resource, etc.
p pointer to
c, o generic C++ object
h handle
k constant value
g global
* Magic numbers must not be embedded directly in the source code. Use a
const int variable to hold the magic number rather than a #define.
7. Comments : Please comment your code, it makes everyone's life easier.
Comment major
blocks of code explaining what you are about to do (or expect to do). Pay
special attention to cases where the code was written a specific way to work
around a problem, etc. Don't be afraid to be verbose, but please make sure
that whatever comments you use really do add value. Remember that comments
are not a replacement for well written and easily understood code. Rather,
they are meant to augment the code by detailing information which may not be
immediately apparent by looking at the code.
eg1: an example of useless comments (DON'T do this)
pInput = fopen("abc.txt, "r"); // open the file
if (pInput != NULL) // is the file open?
{
nValue = fgetc(pInput); // get the value
fclose(pInput); // close the file
}
eg2: an example of useful comments (DO do this)
//
// iterate through the mount list to find the requested path
//
int nCount = m_pcMountList->GetCount();
for (int i = 0; i < nCount && !pFoundItem; i++)
{
CFccMountItem* pItem = m_pcMountList->GetAt(i);
assert(pItem != 0);
if (pItem && pItem->IsValid())
{
//
// check if the specified path is a child of the mount
// point for this mount item - i.e. does the path
// begin with the same string as the mount point. If
// it does, we've found what we were looking for.
//
const char* pszMountpt = pItem->GetMountPointName();
assert(pszMountpt);
if (pszMountpt && (0 == strncmp(pszMountpt, pszMountPath,
strlen(pszMountpt))))
{
pFoundItem = pItem;
break;
}
}
}
//
// some useful comments about the next block of code
//
8. File level comments are to be included in all source and header files.
Module name, author, a general description of the code or class contained in
the file, and a copyright notice should be included as per the sample below.
The leading and trailing lines (with all the asterisks) should be 78
characters long to serve as a reference ruler for gauging the length of code
lines.
//****************************************************************************
//
// Module: mntlist.h
//
// Author: Andy Bounsall
//
// Description: definition of class CFccMountList which maintains a list of
// CFccMountItems representing all mountable branches of the
// file system.
//
// Copyright 1998 Corel Computer Corp. All rights reserved.
//
//****************************************************************************
9. Function level comments are to be included for all functions/methods.
Function/method name and a general description of the purpose of the
function should be included as per the sample below. The leading and
trailing lines (with all the asterisks) should be 78 characters long to
serve as a reference ruler for gauging the length of code lines.
//***************************************************************************
//
// Method: OpenCamera()
//
// Purpose: Tries to open a device driver and, if successful, sends an
// OPEN_CAMERA IOCTL request to initialize the device with the
// desired video mode.
//
//***************************************************************************
10. Function/method size: bigger is not better. Functions and methods should
be kept to a maximum of 40-50 lines. Larger methods should be broken down
into several smaller methods.
11. Curly braces
a) location must be on the next line and right underneath the 1st coding
column of the line directly above it.
eg. void SetDummyVar(int nDummy)
{
m_nDummy = nDummy;
if (nDummy > knFunkyLimit)
{
DoSomethingFunky();
}
}
b) All statements following if, while, for, ... etc. must be enclosed within
braces even if it is only 1 line.
12. Spacing
a) there must be spaces separating each binary operator and each keyword.
eg. a = b; and not a=b
if (l == m) and not if(l==m)
b) blank spaces should not be left between method/function names and the
opening bracket.
c) blank spaces should not be left immediately after an opening bracket, nor
immediately before a closing bracket
eg. DoIt(this); and not DoIt( this );
if (test) and not if ( test )
d) one blank space should be left before the opening bracket of if (), while
(), and switch () statements.
e) multiple parameters to methods/functions should be separated by a comma
followed by a single blank space (not a tab)
eg. DoIt(this, that, theOther);
void Whatever(int nCount, const char* pszName)
o function arguments which do not fit on a single line should be
placed on multiple lines, indented so that the additional
arguments are aligned with the arguments on the preceding line
eg. void CvideoLine::ExecuteCommand(int nOpcode,
void* pParams)
g) leave blank lines between sections of code. Each major section of code
should include a comment explaining what it's purpose is.
* leave two blank lines between the end of one function/method and the
header for the following function/method.
13. Assertions and debug only code should be used liberally to check for
validity of all pointers; range/value validation of function and method
parameters; assumed states, conditions, etc., etc. The assert() macro is
your friend - make use of it to validate assumptions, but don't try to use
it as a replacement for handling runtime errors. (If you're not sure how to
properly use assertions, please ask your PL). The assert() macro compiles to
nothing in Release builds (i.e. when NDEBUG is undefined). Debug code other
than these macros should be bracketed within #ifndef NDEBUG ... #endif
conditionals so that it is excluded from Release builds.
14. Compilation conditionals, with the exception of debug code noted above,
should be avoided since they make the source code difficult to read and
maintain. Old or unwanted code should be deleted from the source files prior
to check-in. Source safes history feature can be used to retrieve an old
version of the file if the old code is ever required again.
15. Duplicate blocks of code should be avoided. If the same code is needed
in more than one location, place it in a separate function and call it from
where ever it's needed.
16. Goto statements should not be used.
17. Return: functions and methods should be structured to have a single
return.
18. Switch statements must always handle the default: case. If all expected
cases have otherwise been handled, the default: case should force an
assertion failure. Case statements should be indented by 1 tab and separated
from each other by 1 blank line. Code within each case should be kept to a
minimum - i.e. call a function from the case statement if more than a few
lines of code are needed.
19. Comparisons for equality against a constant value should list the
constant value first. Its easy to miss one of the equals signs - this way
the compiler will catch it if you do.
eg. if (-1 == m_nResult) rather than if (m_nResult == -1)
20. Header files must not include other header files (to prevent header file
bloat). Use forward class references to inform compiler of required data
types.
21. Filenames: source files should have .cpp extension. Header files should
have a .h extension. All filenames should be created using only lower case
characters. All filenames in #include statements should also be written in
lower case. Source and header files should normally reside in the same
directory. Large projects should be split up into smaller sub-projects to
keep the number of source files in each directory manageable.
22. Localization: text which will be visible to the user should never be
embedded within the source code. All string literals should be placed in a
separate header file to ease the pain of possible future translation.
23. member variables: all member variables must be initialized by the class
constructor. Whenever possible, member variables should be initialized in
the constructors initialization list rather than by assignment within the
body of the constructor.
24. delete operations should be followed by an immediate reassignment of the
associated pointer with a NULL value as in the following example, even if
the pointer is about to go out of scope. (Remember to use the array modifier
when deleting a dynamically allocated array). Any accidental attempt to use
the pointer following its deletion will generate an immediate protection
fault when the code is executed, which is much easier to find than
unpredictable behaviour caused by using and invalid pointer.
eg. delete [] pstrFilename, pstrFilename = 0;
25. References should be used as parameters/return types rather than
pointers whenever a NULL value is not permitted. This reduces the
opportunity for error and means that the receiver does not have to handle
the possibility of a NULL value.
26. const modifier is to be used where ever possible, for pointer/reference
parameters and return values and for methods which do not modify the class.
27. C++ style casts (dynamic_cast, static_cast) should be used rather than
older C style casts. This makes it easy to later find occurrences of
casting. Given a choice, use of dynamic_cast is preferred since it uses
runtime type info to ensure that the cast is valid.
28. Copy constructor & assignment operator: all classes which do not have
complete implementations of both a copy constructor and an assignment
operator, should define private versions of both with no implementation (see
example below). If a user of the class inadvertently writes code which calls
either of these methods, the compiler will generate an error message rather
than using a default mem copy of the data to the new object.
class CFccMountItem public:
//
// construction, destruction
//
CFccMountItem(const char* pszService, const char* pszMountpt);
virtual ~CFccMountItem();
private:
//
// define private versions of copy constructor and assignment
// operator with no implementation. If used by accident, the
// compiler will complain.
//
CFccMountItem(const CFccMountItem&);
CFccMountItem& operator=(const CFccMountItem&);
private:
//
// private member data
//
char* m_pszServiceName;
char* m_pszMountPointName;
};
* Inline methods which contain more than 1 statement must not be coded
within the class declaration. They should instead be coded within the
header file, immediately following the class declaration.
Reply to: