Writing Good Comments

One of the problems people often seem to be having when commenting code is to actually know what to write. A telltale sign is when you find people commenting their class' constructors with // Constructor or an argument for providing a file name with something like /// <param name="filename">File name</param>.

At this level, commenting is a real pain and seems to be a menial task whose cause might be well justified, but which is just too annoying to comply with.

Now the secret to writing good comments and enjoying the process of doing so seems to be the same that makes people write excellent code: your own mentality. The difference is this:

Are you just trying to accomplish some task and all that matters is that your code works? Now commenting becomes a pain.

Or are you creating an unprecedented piece of art that will solve the task at hand so precisely and elegantly that there cannot be a more efficient or clearer solution? Then comments are just one facet in beauty of your creation.

If you see yourself as an artist instead as a grunt, writing good comments and writing great code becomes a a self-sustained motivation: you're only happy with your creation if it looks like a piece of art. Now you want to write clear, concise and useful comments and you're looking for ways to achieve them.

My trick here is to always think about which clues I would need if I was reading the code in front of me for the first time. After some time, you'll become adept at this way of thinking and you'll quickly see what questions a reader of your code will have and how to answer them.