Commenting Styles on Functions with Numerous Parameters

I ran into a new sub-reddit today called /r/ReadableCode.  In this brand new sub-reddit, the top topic was this:

How I comment function calls with a lot of parameters (which linked to this image: http://i.imgur.com/C9kOjXh.jpg)

I thought it was an interesting manner of commenting the arguments in a function with a ton of arguments.  I had never seen this before, but I admit it was visually pleasing.  I have questions about how easily maintainable these comments are, especially if you start copy-pasting this, but it was definitely interesting.

But the real gold was in the comments, as often is the case on reddit.  There was a fun discussion on the various methods of commenting.

There is the method I am most used to, which is separating out each argument onto it’s own line, and commenting each line:

HANDLE hFile = ::CreateFile(
        fullFileName.c_str(),
        GENERIC_READ,
        FILE_SHARE_READ,    // block other processes from writing 
        NULL,               // default security descriptor
        OPEN_EXISTING,      // error unless file already exists
        NULL,               // fileAttributes -- ignored for OPEN_EXISTING
        NULL                // no template file
        );

The idea of passing in each argument as a variable was interesting, as it gives them a name:

// We will draw on this context to render the cursor into the pixel buffer data
cgContext = CGBitmapContextCreate(baseAddress,
                                  width,
                                  height,
                                  8, // bits per component 
                                  bytesPerRow,
                                  colorspace,
                                  kCGImageAlphaPremultipliedLast);

I liked the idea of passing in a struct that you have to fill in.

WallSegment segment_middle;
segment_middle.wall = wallData;
segment_middle.start = oldEnd;
segment_middle.end = start + delta * (float)(highlightIndex + 1);
segment_middle.highlight = true;
segment_middle.type = WallSegmentType_Middle;
segment_middle.type_next = WallSegmentType_End;

_AddSegment(segment_middle);
oldEnd = _addWallSegment(segment_middle);

Someone pointed out that some languages support explicit naming of the arguments, which I had forgotten about!

erosion_water(matrix=a, gravity=3, speed=4)

Resources

Google Style Guide – Includes guides for C/C++, Objective-C, Python, HTML/CSS, and JavaScript.  Plus others.

Advertisements

One response to “Commenting Styles on Functions with Numerous Parameters

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s