News for hackers. Stuff that matters.

A comment on Every line of code is always documented. Parent comment

Re:Every line of code is always documented by einhverfr on Saturday February 08, 2014 @10:42PM (#7204251)
Long comments get out of date quickly because it isn't clear how the comments relate to the code on a quick scan. In this case, you want a quick note as to why the code is there. You can add external references if needed.

You don't want to make someone who is editing code stop to think about how it affects the comments.

[ Parent | on HN ]
Re:Every line of code is always documented by tsiki on Sunday February 09, 2014 @04:12AM (#7204946)
>You don't want to make someone who is editing code stop to think about how it affects the comments.

What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?

[ Parent | on HN ]
Re:Every line of code is always documented by einhverfr on Sunday February 09, 2014 @04:59AM (#7205029)
> What's the point of comments then if your general rule is that it should be fine to edit code without changing the comments?

Not without changing the comments. Without stopping to ponder how two paragraphs of comments fit into the code changes. The comments (aside from API documentation) should annotate the code, not the other way around.

[ Parent | on HN ]