Web site:  http://openamiga.org  Open Amiga - Projects20241222 04:32
Content ID:  24
Content title:  styleguide-code
Guideline - Code Styleguide
<- Back to guidelines

Content
    
- Introduction
- Use of braces
- Code comments
- Source file headers


Introduction
    
In order for Hyperion to more easily accept any code from OpenAmiga and to ease other developers helping out with your projects, your source code should follow a certain set of style guidelines. The goal is simply to ease readability and understanding of your code. This code style guide gives a few pointers as to how to write your code.


Use of braces
    
Always put braces on their own line. It may make you code take up more lines but it's far easier to read especially in conditional parts of code where there are many conditional layers. 

if(a==b)
{
 // some code here ..
 if(a!=c)
 {
 }
}



Code comments
    
Litter your code with comments, remember that others will be reading your code and it must be clear what you were trying to do in your code.

Always add a comment header to your functions that explain their basic function, what the parameters are for and what it returns and if there's any specific behaviour any caller must be aware of.

Example function header: 
/*
** Allocate a Dynamic String for usage
**
** buffsize is the initial size of the internal Dynamic string buffer
** memtype is any standard memtype, such as MEMF_PRIVATE, MEMF_SHARED etc.
**
** The returned dynstr must be freed by FreeDynString() after use
** If buffsize is set to '0' a predefined size will be used
**
*/
struct dynstr *GetDynString(uint32 buffsize, uint32 memtype)
{
 ...
}



Source file headers
    
Source and header files should have a generic header that is similar for all projects. Below is an example from the Workbench file lister project containing file description and version history. 

/*
** File:        DosIO.c
** Description: DOS Input/Output Functions
**
** OpenAmiga.org
**  This file is part of the OpenAmiga "Workbench file lister project"
**
** For more information look at:
**   http://openamiga.org/?function=viewproject&projectid=20
**
** Change history:
**  2008-11-13 orgin, added new file header
**  2009-02-10 TSK, completely new ExDir(), new Delete()
**  2009-02-11 TSK, fixed file/dir open functions
**  2009-02-13 orgin, prepared ExDir for column sorting
*/



Miscellaneous
    
- Avoid 'clever code' or compacted code that runs the risk of being misunderstood by other developers. It may look clever and ingenious to you but it's probably unreadable to others which makes it harder to hunt for bugs or adding new features to your code.

- Always write your code and comments with the thought that others must be able to follow what it does and that you yourself must understand the code one year from now and not just for the moment you write it.

- Always use OS4 style library interfaces when available and avoid using __USE_INLINE__