How to Create Effective Comments: Mastering the Art of Code

A blog post about comments? Really?

I am writing this blog for posterity. All I want is to help other people who, like myself might be on the journey to become a master at the art of coding.

It would seem that being great at coding is creating habits which give back in the far future and slowing down software rot at individual level.

With that in mind, we will take the most neglected part of coding and bring it to forefront: Commenting.

There have been multiple blogs written about comments, yet personal records are sparse and difficult to find.

One thing is for certain and everyone has a clear consensus on this, you don't need to comment all of your code, only those parts which could be re-used in the future by another developer.

My findings on Comments for methods.

Getting to comments, what could be the fields that would help a future developer use your methods?

Lets see, going through stackoverflow and wide array(hehe) of blogs, I have narrowed it down to 5 items:

1. Description of what the methods does and if there are some special instructions for the developer before using it.
2. Author. I think putting an author name for a method gives a sense of accountability and pride for your work, which might lead to the author creating a clean and beautiful code(more on that in later posts).
3. Modified date: The last modified date for any method to make it clear what and the last change was.
4. Exceptions, errors: This might serve as a warning to the next developer as to what might lead to a breakdown of the code. Going through this yourself for your own methods might even lead to finding errors you didn't know you had.
5. Return: a clear sentence that says what the developer might expect in return complete with data structure and the data expectation.

1 2 3 4 5 6 7

/** *A brief description of the method *@author name-of-author *@since date of creation *@throws Exception or error that could be expected *@Return List of all Objects that will be returnable */

Inline comments.

"I did it this way because nothing else works. Why don't you try another implementation?"

Now that we have thought of the best way to write comments for methods, we sometimes just need to create inline comments just to explain some piece of code in the best way possible.

So what do we add in inline comments?

I follow a clear method to keep these comments to a minimum(Nobody likes to read too much anyway),

Only leave inline comments for other programmers who:

• Might get stuck
• Might take a while to understand your code
• Might need an explanation of why certain implementation is the best possible thing for now.

Also, add TODOs to let other programmers know that a certain method can be improved in the future with another implementation.

In the end, its a kind of an Art

At the end of the day, you could totally ignore all this and still write great code. Yet, to be a master, you need to be improving at every part of it. So why not start with something that takes no technical expertise? In essence, to reach a Goal, small habits take you most of the way.