Hello. Today I would like to talk to you about comments.
What I would like to know is, is there any such as overcommenting? Because if so, I'm guilty of it, and nobody has told me. This is largely because I can never get an honest critique of my coding style, because A) it's not the sort of thing people generally stop to critique and B) everyone I know who knows an int from a hole in the ground is a total ass. Not that I'm not counting the people here in that demographic, but when you're in the desert you can't complain about the sand in the water.
Anyway! I've long suspected that I've been quietly discriminated against for putting too much English in my logical gobbledygook, so I'd like y'alls input on whether this is too much, not enough, or juuuuust right.
A (completely at random pulled out of my current project) example:
void SizeToClient(HWND hWnd, int width, int height)
{
// Set the size of a window based on the desired client area size
// hWnd: Handle of window to resize
// width, height: Desired client area width and height
RECT rcWindow; // Current dimensions of entire window
RECT rcClient; // Current dimensions of client area
int borderWidth; // Total width of non-client area
int borderHeight; // Total height of non-client area
// Get dimensions of whole window and client area
GetWindowRect(hWnd, &rcWindow);
GetClientRect(hWnd, &rcClient);
// Get the difference in size between the whole window and the client area
borderWidth = (rcWindow.right - rcWindow.left) - rcClient.right;
borderHeight = (rcWindow.bottom - rcWindow.top) - rcClient.bottom;
// Resize window to make client area size match width/height
MoveWindow(
hWnd, // Window handle
rcWindow.left, // Window x position (keep)
rcWindow.top, // Window y position (keep)
width + borderWidth, // New window width
height + borderHeight, // New window height
true // Repaint window immediately
);
}
Pretty much everything I write follows the same format: one-line function summary, explanation of arguments, explanation of variables, a line before each logical chunk of code, and an explanation of arguments on any big function call. Is this really so bad, or am I right to suspect that most programmers are simply very proud of their ability to read and write confusing language* and don't like having things explained to them?
* I've built something of a mini-career out of my proven ability to parse out broken code left by insane developers who will apparently explode if they write a single letter of any sort of documentation.
Author
Topic: Programmers' Wanking Corner (Read 20780 times)