{"id":82033,"date":"2008-07-30T22:19:43","date_gmt":"2008-07-30T22:19:43","guid":{"rendered":"https:\/\/www.webstaging.red-gate.com\/simple-talk\/?p=73193"},"modified":"2019-05-22T10:09:38","modified_gmt":"2019-05-22T10:09:38","slug":"commenting-your-code","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/blogs\/commenting-your-code\/","title":{"rendered":"Commenting your code"},"content":{"rendered":"

As I am easing back into real life from writing the book, I am in search of easy targets for blogging.\u00a0 My boss mentioned this blog<\/a> over on Jeff Atwood’s Coding Horror Blog and it got me thinking about commenting.\u00a0 His advice is to only comment “why” the code works.\u00a0 I can’t quite agree, because the code he claims to be acceptable is:<\/p>\n

private double SquareRootApproximation(n) {
\n\u00a0 r = n \/ 2;
\n\u00a0 while ( abs( r – (n\/r) ) > t ) {
\n\u00a0\u00a0\u00a0 r = 0.5 * ( r + (n\/r) );
\n\u00a0 }
\n\u00a0 return r;
\n}
\nSystem.out.println( “r = ” + SquareRootApproximation(r) );<\/p>\n

I mean, it is better than some code I have seen,\u00a0 but still, I would like a bit more information about why this works.\u00a0 Maybe the name of the algorithm used, or at least what to do if this fails to provide the expected results.\u00a0 Admittedly this is probably something that could be easily found, but most algorithms are not.\u00a0 Comments in my mind should at least lead you to understand the mindset of the programmer.\u00a0 What would actually improve this code in my mind is to change the variables to full words (though in this case it might not make sense to do this.)<\/p>\n

On an extremely different side of things is this article<\/a> from “Edgewood Solutions Engineers<\/a>” on mssqltips.com. Their answer is to explain what the code is doing in simple terms, making sure to comment almost everything.\u00a0 They have a very elaborate header devised, with dependencies, both users of the object and objects it used.\u00a0 Most of what is said seems a bit like overkill, but their point here “Comment all of the major code blocks of the code and the critical minor points that can be easily overlooked such as a obscure WHERE clause.” is a good one.\u00a0 I generally pepper my code with comments where I think it will be hard to debug for myself later, with a consideration for others, particularly when those others will call me to explain the code.<\/p>\n

Which brings me to my commenting philosophy. I personally think you have to comment to the expected lowest common denominator.\u00a0 Think of the dumbest person who could have the need to read your code who is also qualified to have their job (otherwise you would have to write instructions on every line of code). If the qualified person can figure out what you are doing just by your naming conventions and , then it doesn’t need comments. But if that person would look at the code and reasonable figure it out, then there is no need to comment the code.\u00a0 What this requires is a few things:<\/p>\n