Saying just the right amount is an art. It is hard to say just enough to convey your point while not getting overly verbose.
Take for example a simple directive: “Go”. While this directive lets us know what to do it lacks information. Where should I go? Why should I go? Does this mean me physically or something I am supposed to do?
Update the example to this: “Go down the street, take a right, go 3.4 mils, turn left, watch for traffic, cross the street. go into Sav-A-Lot Grocery, grab some cookies, and come back”. This is very exact but may be overly verbose. If I already know were the Sav-A-Lot is then this information is arbitrary and doesn’t really add much to the overall context. This example does, however, give more information as to the purpose of the directive is.
Perhaps a median ground is best: “Go get some cookies”. The directive is meaningful, succinct, and has enough information to keep the person targeted by the statement from being overly curious.
The same thing applies to code comments. You should write enough so that the situation is clearly explained without going into too much detail. If you find yourself not writing comments or writing one or two words, this is the equivalent of “Go”. If you find yourself describing what the code itself does, this is the equivalent of the overly verbose version of “Go…”. Since the code itself offers direction, the purpose of the comments should be to simply tell what the overall purpose of the code is and why it is doing the things it does. This is the equivalent of the “Go get some cookies” directive. It is enough information to provide some help but not too little or too much.
