commenting code [closed]

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. 开发者_StackOverflow社区 Closed 10 years ago.

whats the most professional and informative way of commenting code. Are there any standards out there?

p.s. it doesn't have to be javadoc, just info on what to include - any common layouts etc

cheers guys

---

There's a big difference between commenting internal method code and commenting APIs.

For code, I'm not familiar of specific practices or layouts. "Use common sense" is the best one. Don't document anything that is obvious from the code, etc, but document everything that is not immediately clear. And remember, the one thing worse than code without comments is code with outdated comments. More comments mean more stuff that needs to be updated.

For API documentation, there are two approaches. The document-everything-in-tons-of-details (proposed by Sun), and the more agile (propose the important parts only). In many places, you are not expected to document API stuff that is obvious from the signature.

While a complete documentation of the method (the sun approach) is important to have a well fleshed up spec, my research shows that it makes it more difficult to spot important caveats, likely leading to more errors.

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

---

Java has code commenting standards defined. Try this http://www.oracle.com/technetwork/java/codeconv-138413.html

---

I think it depends, javadocs are nice for larger projects. If it's something for a small project or school assignment a small description before the method header will do nicely and maybe some interspersed comments inside the methods in case you are doing things in an unorthodox way. Before any of these though I would recommend you give your methods informative names as well as variables and parameters this way it's easier to infer what the method is doing than reading and trying to figure out exactly what each parameter is for etc....

---

Steve McConnel's book Code Complete - undoubtedly the best book on how to write software - has a whole chapter on how to write comments and otherwise ensure your code is understood - called "self-documenting code".

---

I was once taught to use pre-conditions, post-conditions, and comment on which data structure each method will modify. This was in school. I've never saw this done in industry.

---

1. I use to create file /META-INF/CHANGELOG and keep it uptodate (e.g. 10.12.2010 added feature A).
2. Ussualy I create README in source folder and breafly describe whole project in it (for example: project has feature A and these classes are handling feature A. To add subfeature subA modify class Foo...)
3. In comments try to describe what and why are you doing but not how you do it (e.g. "let's find max value in prices, we will show it in table header"... but not: "finding max value in for loop")