How Should I Go About Commenting My Code?

The comment is also written in the first person (“I loop…”), which isn’t relevant to the context of what the program is doing either..Before reading on, how might you tweak example one in order to improve the utility of the comment?Now take a look at example two..It is slightly more useful in that the manner it is written is more relevant to the program itself..However, yet again it just tells you what the code is doing..In fact, the comment repeats the method name..Why did this method need to be written?.It may be an important step in process, but there is no context to what that process may be..Again, see if you can think of a way you might tweak the existing comment to improve it?Potential tweaks for improvement:Example 1 (revised):#selects all of an individual user's current stocksdef my_stocks trades = Trade.all.select {|trade| trade.investor_id == self.id} not_sold = trades.select {|trade| trade.bought_sold == "bought"}endExample 2 (revised):# called during a stock purchase/sale to assure that each # transaction occurs only once.def transaction_already_completed?.if self.status != "pending" false else true end endWhat did we do differently in example one?.It is still not perfect, but it does provide more insight into the utility of the function, since we do not have the entire program in front of us to review..However, with this comment we know that there is an important distinction between stocks that have been bought and sold, and that we only want to return stocks from a given user that they own.Example two is an even stronger revision..This revision provides the context that this method is flexible enough to be used in both stock purchases and sales.. More details

Leave a Reply