====== GECKO3 Coding Guidelines ======
In order to keep code readable and consistent, please use the coding guidelines shown on this page. 


===== C/C++ =====
  *  File names: small, use underline for separation ''usb_tmc.c''
  *  Variables: small, without underlines ''numberOfGeckos''
  *  Function names: Capitalized, without underlines: ''GeckoGetFw()''
  *  Constants: completely in uppercase with underlines: ''BUFFER_SIZE''

==== File and Function Header ====
The headers have to be commented in the [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]] style. 
After [[http://www.stack.nl/~dimitri/doxygen/commands.html/|commenting]] you can use therefore Doxygen to create your source code documentation.

=== Demo File Header ===
<code c>
/* GECKO3COM
 *
 * Copyright (C) 2008 by
 *   ___    ____  _   _
 *  (  _`\ (  __)( ) ( )
 *  | (_) )| (_  | |_| |   Bern University of Applied Sciences
 *  |  _ <'|  _) |  _  |   School of Engineering and
 *  | (_) )| |   | | | |   Information Technology
 *  (____/'(_)   (_) (_)
 *
 *
 * 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.
 *
 * This program 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/>.
 */ 

/*************************************************************************
 * \file    usb_tmc.c
/************************************************************************/
/* \brief   Implements the USB TMC protocol.
 *************************************************************************
 * \author  Lukas Kohler kll1 bfh.ch
 * \date    2009-02-04 kll1 created
 ************************************************************************/
</code>

=== Demo Function Header ===
<code c>
/************************************************************************/
/* \brief      Reads all USB devices and returns the amount of found 
 *             Gecko3 systems.
 *************************************************************************
 * \param[in]  char print: if not 0, prints more information 
 * \param[out] -
 * \return     int numberOfGeckos: amount of found Gecko3's
 * \warning    The amount of Gecko3's is limited by MAX_GECKOS_ON_USB!
 *************************************************************************
 * \author     Lukas Kohler kll1 bfh.ch
 * \date       2009-02-04 kll1 created
 * \test       OK
 ************************************************************************/
</code>


==== Further Reading ====
http://www.mono-project.com/Coding_Guidelines


===== VHDL =====
To get a good an structured VHDL project, it's important to use some basic code guidelines. First of all, use never spaces in names. In place of a space use an underline.

==== File names ====
Every VHDL file in a project has a unique and well chosen name. The file name must be the same as the ENTITY name in the file.

E.g.: File named: adder_gen.vhd
<code vhdl> 
        entity adder_gen is
          generic
            ...
          port
            ...
        end adder_gen;
</code>


==== File header ====
Every VHDL file has a header part. This part contains the developer's name and some infos concerning the file. If you develop for the GECKO3 you have to take the following header template.
<code vhdl>
-- ------------------------------------------------------------------------
-- Filename          : test_name.vhd
-- Modelname         : 
-- Title             : 
-- Purpose           :
-- Author(s)         : Muster || muster@bfh.ch
-- Comment           :
-- Assumptions       :
-- Limitations       :
-- Known errors      :
-- Specification ref : Part of ...
-- Description       : Short description
-- ------------------------------------------------------------------------
-- Modification history:
-- ------------------------------------------------------------------------
-- Version  | Author | Date       | Changes made
-- ------------------------------------------------------------------------
-- 1.0      | hga3   | 04.07.2008 | inital version
--          |        |            | 
</code>


==== Name of signals and variables ====
To get informations about the function of a signal or a variable during the programming follow, it's important to choose a name as good as possible. The following obligatory conventions should used:


=== Signals in an entity === 
In an entity you have ports to communicate with the outside world of your component those signals can take one of the following types: IN, OUT, BUFFER, INOUT. In the name of the ports it's important to get informations about the port, also take the following name conventions: \\

^           Portnames           ^^^
^ Type        ^ info              ^    name prefix    |
| IN          | input             |    i_             |
| OUT         | output            |    o_             |
| BUFFER      | buffered output   |    b_             |
| INOUT       | bidirectional port|    io_            |


To get informations about the activity, the conventions are as follows: \\

low active  n \\
high active “nothing” \\

E.g.: Signal name
<code vhdl>
   i_nReset   -- name for a negative reset (input)
   i_Clk      -- name for a positive clock (input)
</code>

=== GENERICS ===
For a GENERIC (generic value) use g_ as name prefix \\

=== In the ARCHITECTURE ===
The CONSTANTS, SIGNALS and VARIABLES available in the architecture of your IP core should be named as follows:\\

//CONSTANTS// -> The name of a constant is written in capital letters\\
//SIGNALS  // -> The name of a signal starts with a s_ \\
//VARIABLE // -> The name of a variable starts with a v_ \\