All headers and source files have to start with the following lines:
/*
* NASPRO - NASPRO Architecture for Sound PROcessing
*
* Core library
*
*
* copyright notice(s)
*
* This library 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 2 of the License, or
* (at your option) any later version.
*
* This library 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, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
/*!
* \file realtive_path/file_name
* \author author #1
...
* \author author #n
* \date last modify date (YYYY-MM-DD hh:mm in GMT time)
* \brief brief file description
*
* optional longer file description
*/
The first comment contains the GPL notice, while the second is a Doxygen-compatible comment with informations about the file.
Header files
Public header files must contain the following lines just after the above code block:
#ifndef _NACORE_MYFILE_H
# define _NACORE_MYFILE_H 1
and must end with:
#endif /* !_NACORE_MYFILE_H */
While for private header files it goes like this:
#ifndef _NACORE_LIB_MYFILE_H
# define _NACORE_LIB_MYFILE_H 1
...
#endif /* !_NACORE_LIB_MYFILE_H */
This is a very widespread technique which prevents including each header file more than once.
#include directives
It's preferable that all #include (and strictly related #define) directives are placed just after the parts described before, so that a reader knows each file's dependencies right from the start.
Then, when a file needs to include two files, one of which is already included by the other one, it's better to explicitly include it the same. In other words: if a.h relies on b.h and c.h, while b.h already #includes c.h, a.h has to #include c.h as well. This is done because if someday b.h won't depend anymore on c.h, a.h will continue to compile cleanly.
Furthermore, it is better to organize #include directives in blocks of inclusions from every single library, separated by a newline, proceeding from the most general to the most specific ones.
C++ compatibility
In order to avoid namespace pollution when including public header files from C++ sources, two macros have to be used in such header files: NACORE_BEGIN_C_DECLS and NACORE_END_C_DECLS (both defined in include/NASPRO/core/cpp.h).
The former has to be put just after the inclusions, while the latter should come right before the final #endif, so that all declarations are between them.
Example
Here follows an example to clarify things, and avoid confusion, somewhat:
include/NASPRO/core/print_time.h
/*
* NASPRO - NASPRO Architecture for Sound PROcessing
*
* Core library
*
*
* Copyright (c) 2007 Stefano D'Angelo <zanga.mail@gmail.com>
*
* This library 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 2 of the License, or
* (at your option) any later version.
*
* This library 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, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
/*!
* \file include/NASPRO/core/print_time.h
* \author Stefano D'Angelo
* \date 2007-06-16 05:12
* \brief Example public header.
*
* This is just a public header example meant to show the basic file layout
* conventions.
*/
#ifndef _NACORE_PRINT_TIME_H
# define _NACORE_PRINT_TIME_H 1
#include <sys/time.h>
#include <NASPRO/core/cpp.h>
NACORE_BEGIN_C_DECLS
void
print_time(struct timeval *tp);
NACORE_END_C_DECLS
#endif /* !_NACORE_PRINT_TIME_H */
lib/print_time.c
/*
* NASPRO - NASPRO Architecture for Sound PROcessing
*
* Core library
*
*
* Copyright (c) 2007 Stefano D'Angelo <zanga.mail@gmail.com>
*
* This library 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 2 of the License, or
* (at your option) any later version.
*
* This library 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, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
/*!
* \file lib/print_time.c
* \author Stefano D'Angelo
* \date 2007-06-16 05:12
* \brief Example source file.
*
* This is just a source file example meant to show the basic file layout
* conventions.
*/
#include <stdio.h>
#include <sys/time.h>
#include <NASPRO/core/print_time.h>
void
print_time(struct timeval *tp)
{
printf("Seconds: %d\n", tp->tv_sec);
printf("Microseconds: %d\n", tp->tv_usec);
}
