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)