next up previous contents
Next: 13 Test Bench Up: VYA Doc Previous: 11 VYA Systems   Contents


12 Coding Style

A uniform look and feel improves the re-usability of code, and a well-defined coding style helps achieve this. VYA therefore adopts the coding style set forth in [1] with some additions as outlined below. Regarding the naming conventions: names of files, variables, types, etc., start with lower case letters. Multiple words within a name are separated by upper case letters; e.g. nrPixelsPerImage. Exceptions may make sense, e.g. YinData. All processes with video i/o must be derived from class VYAprocess which is provided in vya.h,cc.

12.1 File Names

Following [1], every process and every process network must reside in a separate file. The same name is used for the process (network) and the corresponding .cc and .h files, although the file names use lower case only:

12.2 Variable Names

The choice of variable names greatly impacts the readability of code. The meaning of c = a * b; is much less obvious than the meaning of nrPixelsPerImage = imgWidth * imgHeight; VYA therefore requires the use of clear and descriptive names for variables, ports, etc. When long names are abbreviated, the meaning of the abbreviation must be explained with a comment.

12.3 Constant Names

Names of constants are in capitals, e.g. PI. Multiple words within a name are separated by underscores, e.g. TWO_PI.

12.4 Port Names

Port names are standardized as shown in Figure 1 - Figure 3. From these so-called "base names" which are repeated in the table below, the names of the actual parameters, formal parameters and variables of a process or process network are derived. Table 4 shows this for a port called baseName. Variables may be given more appropriate names where applicable.

Table 3: Base names of standard I/O ports
port type base name
Video in Yin, Uin, Vin, Rin, Gin, Bin, Cin
Video out Yout, Uout, Vout, Rout, Gout, Bout, Cout
Line length in lineLenIn, YlineLenIn, UVlineLenIn
Line length out lineLenOut, YlineLenOut, UVlineLenOut
Image width in imgWidthIn, YimgWidthIn, UVimgWidthIn
Image width out imgWidthOut, YimgWidthOut, UVimgWidthOut
Image height in imgHeightIn, YimgHeightIn, UVimgHeightIn
Image height out imgHeightOut, YimgHeightOut, UVimgHeightOut
Image type in imgTypeIn
Image type out imgTypeOut

Table 4: Parameter names
parameter name
port (formal) baseNameP
fifo (actual) baseNameF
variable baseName

12.5 Fifo Names

The fifos of a process network should indicate the type of data traveling through it. VYA's base names for standard fifos are shown below. When there is more than one fifo of the same type, the base names are followed by a number.

Table 5: Base names of standard fifos
fifo type base name
Video Y, U, V, R, G, B, C
Line length lineL, YlineL, UVlineL
Image width imgW, YimgW, UVimgW
Image height imgH, YimgH, YimgW
Image type imgT

12.6 Process and Process Network Names

Processes and process networks must be given descriptive names.


Statements or groups of statements that are not completely obvious should be explained by means of comments. As outlined above, this includes the bit precision of mathematical operations.

12.8 Headers

All files representing VYA processes and process networks should be preceded by the header shown below. Fields that don't apply to a particular file are designated "n/a". The headers may be automatically generated by the version control system so that they are always up to date.

12.9 Layout

The layout of a program significantly impacts its readability. Brackets delimiting flow statements (for, while, if, ...) should be properly aligned. Comments should follow or be vertically aligned with the statement(s) they refer to. Spaces should be used instead of tabs to prevent the layout from being messed up in editors with different tab settings.

12.10 Error Signalling and Diagnostics

The number of print statements in VYA code should be kept to a minimum. Print statements inserted for debugging purposes during module development should be removed prior to acceptance into a library. Two techniques are used for signalling errors caused by improper application of a VYA module in a larger system. Errors in low-rate control parameters are signalled with unconditional print statements, e.g. as in the VYAcheckSize and VYAcheckPrecicion functions. Errors in pixel-rate video data are optionally checked with the assert function, for instance

  assert(!((Yin[i] < 0) || (Yin[i] > Ymax)));

To preserve simulation speed, assert should by default be turned off by defining compiler directive -DNDEBUG in the makefile. For diagnostic purposes, the makefile can also enable a verbose mode through optional compiler directive -DVERBOSE, to be used for instance as follows:

  #ifdef VERBOSE
    cout << fullName() 
         << ": input line length = " 
         << lineLengthIn 
         << endl;

The fullName function should always be included to identify the issuing process.

12.11 Miscellaneous

Additional coding rules for writing re-usable DSP algorithms are given in [4]. They include:

next up previous contents
Next: 13 Test Bench Up: VYA Doc Previous: 11 VYA Systems   Contents
© Copyright Koninklijke Philips Electronics NV 2006