Comment Code

Question

What is the most professional and informative way of commenting code. Are there any standards?

ps it should not be javadoc, just information on what to include - any general layouts, etc.

welcomes guys

Answer 1

There is a big difference between the comments of the internal method code and the comments of the API.

For code, I am not familiar with specific practices or layouts. "Use common sense" is the best. Do not document anything that is obvious from the code, etc., but document everything that is not immediately clear. And remember that one thing worse than code without comments is code with outdated comments. Additional comments mean more things that need to be updated.

There are two approaches to API documentation. An all-in-one detail document (proposed by Sun) and more flexible (offering important parts only). In many places, you do not have to document API material, which is obvious from the signature.

While the full documentation of the method (approach to the sun) is important in order to have a well-formed specification, my research shows that this makes it difficult to identify important caveats, which can lead to more errors.

For APIs, see also: Creating Excellent API Documentation: Tools and Techniques

Answer 2

Java has certain standards for commenting on code. Try http://www.oracle.com/technetwork/java/codeconv-138413.html

Answer 3

I think it depends, javadocs are good for large projects. If this is something for a small project or school assignment, a short description before the method heading will be well done and maybe some interspersed comments inside the methods if you are doing something in an unorthodox way. Before any of them, although I would recommend that you give your methods informative names, as well as variables and parameters in this way, it is easier to determine what this method does than to read and try to find out what exactly each parameter is for etc ....

Answer 4

Code Complete's book by Steve McConnell - undoubtedly the best book on how to write software - contains an entire chapter on how to write comments and otherwise ensure that your code is understood - called "self-documenting code."

Answer 5

I was once taught to use preconditions, post-conditions, and comments on the data structure that each method will modify. It was at school. I have never seen this in industry.

Answer 6

• I use / META -INF / CHANGELOG to create the file and save it uptodate (for example, the added function 12/10/2010 A).
• Ussualy I create a README in the source folder and roughly describe the entire project in it (for example: the project has function A, and these classes are processed by function A. To add subelement subA modify class Foo ...)
• In the comments, try to describe what and why you do, but not how you do it (for example, “let's find the maximum value in the prices, we will show it in the table heading” ... but not: “find the maximum value for the loop”)