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:

• files myvyaprocess.cc,h define process myVYAprocess
• files myvyaprocessnetwork.cc,h define process network myVYAprocessNetwork

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.

12.7 Comments

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;
  #endif

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:

• Static member variables may not be used, as they are not duplicated for multiple instances and hence cause dangerous side effects.
• Pointers may not be communicated over fifos, as that assumes a shared memory architecture.
• No hard paths to include files may be used, as that limits portability. All paths should be relative to the directory where the module is located.
• Type casts are explicit operations and should preferably be explicit.
• Floating point variables should be used sparingly, as both hardware and software implementations are most likely to use fixed point.
• File I/O is only allowed by frontend, backend and control modules, except for print statements in the verbose mode which any module may have.