Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.java.programmer > #39796
| From | Wayne <wayne@nospam.invalid> |
|---|---|
| Newsgroups | comp.lang.java.programmer |
| Subject | What Makes for Good Comments? (Part 3 of 4) |
| Date | 2022-07-27 23:44 -0400 |
| Organization | A noiseless patient Spider |
| Message-ID | <tbt0m5$2q0vv$1@dont-email.me> (permalink) |
How Comments A third type of comment is a "how" comment. These are for libraries and reusable modules, and tell the reader how to use your code with their code. The Java "doc" (or "API") comments for Java SE is an example of this. Such docs are usually extracted from comments in the source code. "How" comments are used to describe how to use the methods, fields, and classes of your code. Generally, only public and protected methods and fields need these, but they never hurt to include on private methods too. How comments might describe method argument types and ranges, return value type and range, method semantics, pre- and post- conditions, and use cases (example code). They can include warnings (such as this method is not thread-safe), examples, and references to other documentation. What and why comments are generally not included in such API docs. The how or API comments (also called doc comments) are specially treated in Java, and are converted to HTML using the tool "javadoc". You can control how that is done. Note this tool also examines the code itself, not just the comments, to produce the API docs. How to use that tool and use proper doc comments is beyond the scope of this post, but there are plenty of resources on this topic available on the Internet, for example: <https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html>. How comments should be considered required on all public and protected classes and members of classes. Feedback Welcome! -- Wayne
Back to comp.lang.java.programmer | Previous | Next — Next in thread | Find similar | Unroll thread
What Makes for Good Comments? (Part 3 of 4) Wayne <wayne@nospam.invalid> - 2022-07-27 23:44 -0400
Re: What Makes for Good Comments? (Part 3 of 4) Martin Gregorie <martin@mydomain.invalid> - 2022-07-28 11:48 +0000
Re: What Makes for Good Comments? (Part 3 of 4) Wayne <wayne@nospam.invalid> - 2022-07-28 11:36 -0400
Re: What Makes for Good Comments? (Part 3 of 4) "e.d.pro...@gmail.com" <e.d.programmer@gmail.com> - 2022-08-01 04:40 -0700
csiph-web