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:

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(
        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,
                                  8, // bits per component 

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;

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)


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