How to Write Good Doc Comments for a Class/Method?

Well, software engineers love to jump to the code (minus document) once design is completed. Majority of them do not write the help text around the class or methods. Some of them do write but they do not provide enough information. There are various reasons for the lack of enough comments within a class. Some of them are lack of time, lack of writing/articulation skills etc.

Following are some of the questions which would you like to answer as part of comments for method or a class:

• Functionality: What does the class or the method do? You may want to provide information regarding the business requirement that the component fulfills. You may also want to write about the key attributes and behaviors of the class.
• Inbound Communication: Who uses the class or calls the method on the class and why? This is also called as inbound communication of the class.
• Outbound Communication: Which classes are called by the methods of the class? This is also called as outbound communication of the class.
• Failure Scenarios: You may want to mention about key scenarios when failure happens and also how the failures are handled. This can be used to represent reliability aspect of the software code.

Above is the set of minimum information that you can provide for a class and their methods. The information increases the understandability of the method and the class and hence, enhances usability aspect of software quality. Thus, that increases overall quality of the software code written by you.