C PROGRAMMING

# Commenting And Documentation

Article by:

## General Tips

• Always use \\ style comments where possible. This allows you to use /* style comments for commenting out large blocks of code when debugging. If you want to comment a block of code which has /* comments inside it, you will run into problems! (unfortunately, */ style comments don’t nest in c).
• However, sometimes you still need to comment out blocks of code which have /* comments already inside them (maybe your using someone elses code?). To do this, you can use the preprocessor trick #if 0 (see code below).
  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17  // This is a single lined comment, and the preferred way of doing things /* This is a multilined comment. And should be used sparingly as these don't nest */ // The following example shows how you can comment out code blocks // containing "/*" comments using the pre-processor and "#if 0" #if 0 void test1() { /* Annoying multi-line comment in a block of code you want to comment */ } #endif // #if 0 

## C Supports URL’s, Wait What?

Did you know that:

 1  http://www.google.com 

is valid syntax in C? Wait, what? O.K., I was lying, C doesn’t support URLs, but the syntax is still valid! What it actually represents is a label (http:), followed by a single-line comment (//www.google.com).

## Commenting Styles

Some people put function descriptions after the function name and parameters, and before the opening curly brace (for example, some windows driver files). I find this method weird and hard to read.

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30  NTSTATUS DriverEntry( IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath ) /*++ Routine Description: Installable driver initialization entry point. This entry point is called directly by the I/O system. Arguments: DriverObject - pointer to the driver object RegistryPath - pointer to a unicode string representing the path, to driver-specific key in the registry. Return Value: STATUS_SUCCESS if successful, STATUS_UNSUCCESSFUL otherwise. --*/ { WDF_DRIVER_CONFIG config; NTSTATUS status; rest of function code... 

## Doxygen

Doxygen is a powerful documentation generator that can be used with the C language. For more information and code examples with Doxygen, go to the Doxygen page.

## Authors

### Geoffrey Hunter

Dude making stuff.