Do you know the best way to track comments when your code is updated?
Rules to Better Code Commenting|ffffc8b7-8e39-4ad1-934a-b27e98089715
v8.0
Posted at
5/08/2019 2:33 PM by
Matthew Wicks
Rule Intro
It's important that you have consistent commenting for your code, which can be used by other developers to quickly determine the workings of the application. The comments should always represent the rationale of the current behaviour.
Page Content
Since applications evolve over time - don't add comments to your code with datetime stamps. If a developer needs to see why the code behaves the way it does right now - your commit history is the best place to tell the story of why the code has evolved.
Commands such as git blame or Visual Studio's annotate are great ways of seeing who and when a line of code was changed.
private void iStopwatchOptionsForm_Resizing(object sender, System.EventArgs e) {
// Don't close this form except closing this application - using hide instead;
if (!this.m_isForceClose) {
// <added by FW, 11/10/2006>
// Remind saving the changes if the options were modified.
if (this.IsOptionsModified) {
if (MessageBox.Show("Do
you want to save the changes?", Me.GetApplicationTitle, MessageBoxButtons.YesNo,
MessageBoxIcon.Warning) = DialogResult.Yes) {
this.SaveOptions()
}
}
// </added>
}
}
Figure: Bad example - timestamped comments add noise to the code

Figure: Good example - we can tell who added the comment using annotations
{6EBF5337-9271-40BC-80AC-620A0DB284E3}
Do you feel this rule needs an update?