Source: http://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryComments.html
Recently, I read up on the blog cleancoder, by Robert C. Martin on Necessary Comments. The blog talks about how having a comment on every single piece of code that you wright is unnecessary. He says that when coding adding comments should be a last resort. He later even gives a good example of when this should be used. He was working with another member of his team for an improvement for their website. Whenever a customer purchases a video from their website it would then also find all the videos that had been purchased by others who had bought that video, and would pick the most popular and recommend it to the customer. They did not want the customer to wait forever for the suggestions so they decided to put the long running functions into another function that would return the previous result from the cache and if more than the N minute had passed, would run the algorithm in a separate thread, and cache the new result. They called this function the “choke function.” However, when they were testing it and trying to improve it when they tried to have other read the code most people would not know what they were trying to do so they kept going back to the diagram and that was wasting time. So, they decided to make a longer explanation of what the code did and they also drew in a diagram. Robert said “This doesn’t happen all the time.… But it does happen; and when it does nothing can be more helpful than a well written, well thought through, comment.”
I decided to read up on the blog because I was taught to have a comment on every line. This way it is clear on what I am doing and if I make a mistake it would be easier to find where in the code it is in. After reading this blog I can see why writing comments on every single function is useless because in the real world there are people who know what you are talking about. However, if you do decide to write a comment on a function make sure it is a well written, well thought out, comment. For myself I think I will still write comments on many of my functions however if it is very simple and easy to understand I will not waste my time writing it.
The Road of CS 