Contributing
Coding style
Source code should be written following the K&R (Kernighan & Ritchie) style with a few modifications.
Line length: max 80 characters
Indentation: 4 spaces (no tabs)
Braces:
Functions: opening brace at next line
Control statements (mandatory): opening brace at same line
Spacing:
2 lines between function definitions
1 line between logical blocks within functions (and between variable declarations and definitions)
Comments:
Documentation of functions and other symbols: balanced, multi-line
/** ... */
comments in reStructuredText format using field lists:param:
and:return:
to document function parameters and return values, respectively, and:c:member:
,:c:func:
,:c:macro:
,:c:struct:
,:c:union:
,:c:enum:
,:c:enumerator:
,:c:type:
,:c:expr:
,:c:var:
from the Sphinx C domain directive to cross-reference other C language constructs or to insert a C expression as inline code.Inline comments in function body: single-line
//
C++ style comments
Naming conventions:
Data structures (
struct
orenum
) and types are named using upper camel case (e.g.,DcmDataSet
), while functions are named using all lower case with underscores (e.g.,dcm_dataset_create()
).Names of
external
functions, data structures, and types that are declared in thedicom.h
header file are prefixed withdcm_
orDcm
. Names ofstatic
functions, types, or data structures declared in*.c
files are never prefixed.
Interface
The library exposes an “object-oriented” application programming interface (API), which provides data structures and functions to store, access, and manipulate the data.
To facilitate portability, the dicom.h
header file is restricted to
C99 version of the standard (C89 + Boolean type from
stdbool.h
+ fixed-width integer types fromstdint.h
/inttypes.h
)Opaque data types
Clear, exact-width integer types (
int16_t
,int32_t
,int64_t
,uint16_t
,uint32_t
, anduint64_t
)Minimal use of enums
Implementation
- The
dicom-data.c
(Part 5),dicom-dict.c
(Part 6), anddicom-file.c
and
dicom-parse.c
(Part 10) are implemented based on the C11 version of the standard.
The Data Set and Sequence data structures are implemented using the battletested uthash headers.
Documentation
Documentation is written in reStructuredText format and HTML documents
are autogenerated using Sphinx.
API documentation is automatically extracted from the comments in the source
code in the dicom.h
header file via the Hawkmoth Sphinx C Autodoc extension, which
relies on Clang
to parse C code.
Documentation files are located under the doc/source
directory of the
repository. To build the documentation, install libclang
development
headers and the Python venv
module, then build with meson
:
meson compile -C builddir html
The generated documentation files will then be located under the
builddir/html
directory. The builddir/html/index.html
HTML document
can be rendered in the web browser.
Testing
Unit test cases are defined and run using check.
Test files are located under /tests
and can be built and run using
meson
:
meson test -C builddir
Dynamic analysis
The source code can be analysed using valgrind.
For example:
valgrind --leak-check=full dcm-dump data/test_files/sm_image.dcm
Unit testing and dynamic analysis can also be performed using the provided Dockerfile (located in the root of the repository):
docker build -t dcm-testing .
docker run dcm-testing