Monday, November 21, 2011

Comment Comments

What do you do if the coding guidelines that apply to the project you're working on require that

- "around 25% - 50% of code should be comments"
- "every source file must have a history section at the top"
- "every method must have java doc or summary tags"
- "the ending bracket of a method must be commented with the method name"

Do you do it because you are required to? Or do you ignore that guideline knowing that you might get into trouble?
Luckily we were able to convince the right people that this makes no sense and that it's the guideline that needs to change. But unfortunately a bit too late: Today I still come across gems like the one below:

/// <summary>
/// calc rectangle with offsets
/// </summary>
/// <param name="index"></param>
/// <param name="offsetX"></param>
/// <param name="offsetY"></param>
/// <param name="left"></param>
/// <param name="top"></param>
/// <param name="width"></param>
/// <param name="height"></param>
/// <returns></returns>
private Rectangle CalculateRectangle(int index, int offsetX, int offsetY, int left, int top, int width, int height)
{
  [...]
} //CalculateRectangle

2 comments:

  1. Off Topic, but theres a new firmware update for the Kinect with "Near Mode", to get objects closer than 50cm with the new SDK and a general important to the kinect itself

    ReplyDelete
  2. Hi Jay

    Thanks for the hint. I'll write a small blog post about that.

    Regards,
    Stefan

    ReplyDelete