Going through an existing C++ code base at the moment. I have to say that a large proportion of it is pretty good. Yet there are very VERY few comments. I find I'm not missing them for the most part. But then I come across some really strange code, that WAS commented. Unfortunately, it was some of those useful comments, you know - along the lines of
/** This method returns the name of the user logged in**/
Now that's great - I can see that Session::getLoggedInUser() does just that. But WHY does it do it in the way it does? It seems a very convoluted method of querying a database and comparing roles and generally mixing things up. So I can see WHAT the code is doing - good, self documenting code - but I can't see WHY the author did it in this particular way. For me - the why is always important. I can determine from the why whether the user tried the standard library method of doing it and found problems that forced them to roll their own, or I can see that the author didn't know that there was a library function that would do it, or I can see that it has to be convoluted to achieve all the hidden side affects that this otherwise simple method may be hiding.
So now, my options are
- Replace the current method with a library method
- Try and debug the current convoluted method
Now - if the previous comment had of been /** This method returns the name of the user logged by using a custom method because of a memory leak in the library method **/ then I'd know not to go down that path.
So - when commenting code, tell me why you're doing the things you're doing. Tell me why you made the design choices you did, why inheritance instead of aggregation? Why are you throwing exceptions by pointer? Otherwise, I'll either assume you knew what you were doing, and continue doing it the same way when I shouldn't, or I might assume you didn't know what you were doing, and go and correct it - when I shouldn't.
