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

GPUView Is Really Useful

Part of my involves doing performance work on the OpenGL driver.  Working on a driver presents all sorts of challenges, and getting performance info is particularly stressful.  Why is an app running slow?  Is it the CPU?  Is it the GPU?  Is it the app?  Is it the driver?  Is some knob not in the right spot?

One of the tools I recently started using that has made my life much easier is GPUView.  GPUView uses Windows Event Trace Logging to illustrate the performance interactions between the GPUs, CPUs, drivers, Windows graphics kernel, and apps in a system.  It would be best if you first read Matt Fisher’s post on his blog describing GPU View.  Matt Fisher was an intern at Microsoft when he developed this tool with Steve Pronovost, a full time engineer at Microsoft.  It’s required reading for learning about GPUView. There are other resources listed below, as far as education and downloading the tool itself.

READ THIS: http://graphics.stanford.edu/~mdfisher/GPUView.html

I admit that I had delayed my education in GPUView for a long time, because I did not quite understand the functionality offered by the tool. If you have never used GPUView before, and you just saw someone using it, it really makes no sense to look at.  But as soon as you understand how the data is being represented, it is really quite remarkable.  You can see how the CPU and GPUs are interacting, whether an app is CPU or GPU limited, and a mess of other things, within minutes of opening a trace.  Add it to your toolkit, if you do any graphics performance related work on Windows.

Resources

Matt Fisher’s GPUView webpage – http://graphics.stanford.edu/~mdfisher/GPUView.html

Windows SDK For Windows 7 – http://www.microsoft.com/en-us/download/details.aspx?id=8279

AMD Presentation at GDC 2012 – http://www.slideserve.com/libitha/using-gpuview-to-understand-your-directx-11-game-jon-story-developer-relations-engineer-amd

Windows SDK for Windows 8 – http://msdn.microsoft.com/en-us/windows/hardware/hh852363.aspx (I couldn’t install this on my Win7 box, as I wanted to view Win8 traces on my main dev machine)