regarding comments going out of date because functions grow...
It's worth saying that this happens not only because codebase is under development but also because functions are often not designed to be explicit and short.
for example, it's not the same thing to write:
1 2 3 4 5 6 7
|
/*
out of date comment because logic not split
*/
void Control::AutoSize()
{
/* Do everything here */
}
|
Or splitting this code into:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
|
// autosize control - end of story
float Control::CalculateFontSize();
// calculate content pixel size
float Control::CalculateContentSize();
// calculate font pixel size
void Control::AutoSize()
{
CalculateFontSize();
CalculateContentSize();
// ... the rest is short and only about what comment says
}
|
See? if you write comment in first case, your comment will surely go out of date soon.
In second case it's much less likely for comments to go out of date because things are explicit, functions become shorter and comments more understandable even if out of date.
This is rather stupid example, but there are many such stupid examples and one reason why comments can't explain the logic behind single "AutoSize" function.
Sometimes you figure this out and split your code, but then forget to update comments.
My point is that writing comments should be followed by good design as well, to minimize unncessary confusion.