[USB-K Devel] coding style, documentation etc.

[Mehmet E. A. <me...@pa...>]

[ Because of some mischanges, some developers may not get this mail. So I'm sending again. ]

Hi all,

Before big changes with USB-K, lets decide about coding style, skeleton of sources, commits etc. These decisions provide us more readable codes, and help us managing sources better.

I made a short list. Day by day we will make enhancements with these items.

1.) Make commits atomic [1]. I mean, if you make changes with one porpose do it and commit. Do NOT do other works with that commit. For example, you need a bug-fix. Then fix it and commit with this message:
 "Bug Fixed #2341241 

  - SCSI device broken error is handled which causes SEGFAULT"

Commit this and make other changes with another commit.

2.) Every source file must contain license header. There are too many different style with writing the license header. I offer this:

<COMMENT START>
@file <FILENAME>

Copyright (C) <YEAR> <PERSON/PEOPLE>

<LICENSE TEXT>

-------<SEPERATOR>---------
What does this file for.

<COMMENT END>

Example:

/*
 * @file general.h
 *
 * Copyright (C) 2010
 *
 * This program 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.
 *
 * See http://www.gnu.org/licenses/ for more information
 *
 ****************************************************************************
 * General headers and definitions of usbk.
 *
 */

3. Use spaces instead of tabulators. This provides us beautiful code :)

4. I have been looking for coding styles at web and I found this style [2]. It seemed me very good. We don't have to accept every method one to one, we can change some.

5. We should use code documentation with a tool, for example Doxygen. I offer Qt-Style Doxygen documenting [3].

6. Language of the project should fully written in English. I offer use gettext for language support.

This list might be extended.

Any suggestions are welcome.

[1] http://en.wikipedia.org/wiki/Atomic_commit#Revision_Control 
[2] C Sources  : http://maultech.com/chrislott/resources/cstyle/indhill-cstyle.html
    C++ Sources: http://doc.trolltech.com/qq/qq13-apis.html
[3] http://www.stack.nl/~dimitri/doxygen/docblocks.html
    http://doc.trolltech.com/qq/qq28-qthelp.html#htmlfilesandhelpprojects

-- 

~ @memre <Mehmet Emre Atasever>
__EOM