{"id":37,"date":"2005-10-09T13:09:06","date_gmt":"2005-10-09T17:09:06","guid":{"rendered":"http:\/\/www.rakkar.org\/blog\/?p=37"},"modified":"2005-10-09T13:09:06","modified_gmt":"2005-10-09T17:09:06","slug":"effective-commenting","status":"publish","type":"post","link":"https:\/\/rakkar.org\/blog\/index.php\/2005\/10\/09\/effective-commenting\/","title":{"rendered":"Effective commenting"},"content":{"rendered":"<p>\t\t\t\tI&#8217;ve been dealing with a lot of code lately at work where I have to look again at stuff I last changed for some particular context 3-6 months ago.  Either that change had a side effect or it broke some other edge condition.  This is especially true with magic numbers, where I tweak the numbers until they work in one particular case in one particular level.<\/p>\n<p>In general, for both myself and others, I see that the most effective comments are those that explain the why, rather than the how or what.  Yet the most common type of comments explain the how or what, rather than the why.<\/p>\n<p>For example<br \/>\n\/\/ Move foward on the balance beam<br \/>\nif (InDistance(10)) then PressStick(foward);<\/p>\n<p>This is much better than nothing but I can usually figure it by in the context.   Here&#8217;s another way to comment it<\/p>\n<p>\/\/ This will ensure that we reach the threshhold range of grabbing the edge<br \/>\nif (InDistance(10)) then PressStick(foward);<\/p>\n<p>With the first comment, I had no way to know if changing the 10 would have broke the code or if pressing forward had other effects.  With the second comment, I could delete the code entirely and implement something else without breaking the dependency.<\/p>\n<p>The golden rule of commenting IMO is to reveal intention.  Code Complete says to comment variables over code but this is just an effect of commenting intention.  Variables tend to reveal intention better than code does.  I&#8217;m going to add this to my coding rules on the front page.\t\t<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve been dealing with a lot of code lately at work where I have to look again at stuff I last changed for some particular context 3-6 months ago. Either that change had a side effect or it broke some other edge condition. This is especially true with magic numbers, where I tweak the numbers [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[2],"tags":[],"_links":{"self":[{"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/posts\/37"}],"collection":[{"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/comments?post=37"}],"version-history":[{"count":0,"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/posts\/37\/revisions"}],"wp:attachment":[{"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/media?parent=37"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/categories?post=37"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rakkar.org\/blog\/index.php\/wp-json\/wp\/v2\/tags?post=37"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}