Wednesday, February 15, 2017

Some comments about comments in code


I was looking at a code review recently and was reminded of the old piece of advice I once received:  "God comments in code do not explain what the code does, they explain why the code does what it does."

I agree completely.  I was looking at some code to validate we use the correct font.  The code would change from normal, to Light, to Bold, etc… and preceding each of those commands was a comment that said "Changing to Light", "Changing to Bold, " etc..  For a simple task like this it is not too hard to figure out why the font is being changed.  In this case, we want to validate the Bold font, the Light font and so on.  But when code gets trickier, the why the code exists becomes much more important.

Oh, one other thing that drives me up a wall.  Typos in comments.  Seriously - if I am looking for the word "Bold" then I want to find that word.  If someone had spelled it "Blod" then search would fail and life can become quite difficult if I need to change the Bold font behavior everywhere it is used.  Fortunately, this doesn't happen very often, but when I see it, I generally try to make a code change to spell the word correctly. 

Questions, comments, concerns and criticisms always welcome,
John

No comments:

Post a Comment