info
Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
What Makes for Good Comments? (Part 3 of 4)
10 views
Skip to first unread message
Wayne
Jul 27, 2022, 11:44:20 PM7/27/22
to
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
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
Martin Gregorie
Jul 28, 2022, 7:48:48 AM7/28/22
to
On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote:
IME and IMO too, a good start for writing any Java class is to create a
document, which should be held in a directory hierarchy where it will be
once its content has been expanded to contain executable Java code. It
should contain:
- a class-level comment describing the purpose of the class and anything
else somebody using it should know about the class as a whole. This
should be followed by a skeletal class definition, i.e. the class
declaration, which should include constants defined and exposed by the
class and possibly some of the more important class-level variables it
contains.
- the class body should contain declarations of the public methods the
class exposes, each preceded by a method-level comment describing the
method's function and anything else a caller should know about its call
parameters and return value.
- the document header should include the package declaration and any
'import' statements needed for it to compile.
- this class definition must compile and produce clean, easily readable
and understandable output when run through javadoc.
This is an idea I swiped from the K&R 'C' book and have used both when
writing code for my own use and when generating module-level documentation
for larger commercial projects.
Its benefit for the designer is that the completed class outlines have
been automatically checked for gross errors and shown to generate
understandable, well laid-out documentation.
Its benefit for system maintainers and for the project as a whole is that,
because class-level documentation is automatically included with the
source code, it is less likely to be lost and more likely to be maintained
as requirements change and bugs are squashed.
In addition, since this structure can easily provide a home for user
manuals, help texts, etc., it makes the maintenance of these documents a
little easier too.
--
Martin | martin at
Gregorie | gregorie dot org
IME and IMO too, a good start for writing any Java class is to create a
document, which should be held in a directory hierarchy where it will be
once its content has been expanded to contain executable Java code. It
should contain:
- a class-level comment describing the purpose of the class and anything
else somebody using it should know about the class as a whole. This
should be followed by a skeletal class definition, i.e. the class
declaration, which should include constants defined and exposed by the
class and possibly some of the more important class-level variables it
contains.
- the class body should contain declarations of the public methods the
class exposes, each preceded by a method-level comment describing the
method's function and anything else a caller should know about its call
parameters and return value.
- the document header should include the package declaration and any
'import' statements needed for it to compile.
- this class definition must compile and produce clean, easily readable
and understandable output when run through javadoc.
This is an idea I swiped from the K&R 'C' book and have used both when
writing code for my own use and when generating module-level documentation
for larger commercial projects.
Its benefit for the designer is that the completed class outlines have
been automatically checked for gross errors and shown to generate
understandable, well laid-out documentation.
Its benefit for system maintainers and for the project as a whole is that,
because class-level documentation is automatically included with the
source code, it is less likely to be lost and more likely to be maintained
as requirements change and bugs are squashed.
In addition, since this structure can easily provide a home for user
manuals, help texts, etc., it makes the maintenance of these documents a
little easier too.
--
Martin | martin at
Gregorie | gregorie dot org
Wayne
Jul 28, 2022, 11:36:37 AM7/28/22
to
On 7/28/2022 7:48 AM, Martin Gregorie wrote:
> On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote:
>
> IME and IMO too, a good start for writing any Java class is to create a
> document, which should be held in a directory hierarchy where it will be
> once its content has been expanded to contain executable Java code. It
> should contain:
>
> - a class-level comment describing the purpose of the class and anything
> else somebody using it should know about the class as a whole. This
> should be followed by a skeletal class definition, i.e. the class
> declaration, which should include constants defined and exposed by the
> class and possibly some of the more important class-level variables it
> contains.
>
> - the class body should contain declarations of the public methods the
> class exposes, each preceded by a method-level comment describing the
> method's function and anything else a caller should know about its call
> parameters and return value.
>
> - the document header should include the package declaration and any
> 'import' statements needed for it to compile.
>
> - this class definition must compile and produce clean, easily readable
> and understandable output when run through javadoc.
> ...
> On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote:
>
> IME and IMO too, a good start for writing any Java class is to create a
> document, which should be held in a directory hierarchy where it will be
> once its content has been expanded to contain executable Java code. It
> should contain:
>
> - a class-level comment describing the purpose of the class and anything
> else somebody using it should know about the class as a whole. This
> should be followed by a skeletal class definition, i.e. the class
> declaration, which should include constants defined and exposed by the
> class and possibly some of the more important class-level variables it
> contains.
>
> - the class body should contain declarations of the public methods the
> class exposes, each preceded by a method-level comment describing the
> method's function and anything else a caller should know about its call
> parameters and return value.
>
> - the document header should include the package declaration and any
> 'import' statements needed for it to compile.
>
> - this class definition must compile and produce clean, easily readable
> and understandable output when run through javadoc.
Exactly right. This is how I brainstorm my code, by creating skeleton classes
with stub public methods. One can easily see the overall structure and
change it around, perhaps playing with several different architectures
before implementing any stubs. And at that point, after creating initial unit
tests and having everything compile, I like to put in "what" comments as
pseudocode for the implementation, which I remove as I create the code.
If I leave off work for another project, the comments show me where I left off.
--
Wayne
e.d.pro...@gmail.com
Aug 1, 2022, 7:40:57 AM8/1/22
to
On Thursday, July 28, 2022 at 7:48:48 AM UTC-4, Martin Gregorie wrote:
> On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote:
>
> IME and IMO too, a good start for writing any Java class is to create a
> document, which should be held in a directory hierarchy where it will be
> once its content has been expanded to contain executable Java code. It
> should contain:
>
I'd say most projects have evolved organically which makes this stuff difficult, we start small then add more and more functionality.
> On Wed, 27 Jul 2022 23:44:04 -0400, Wayne wrote:
>
> IME and IMO too, a good start for writing any Java class is to create a
> document, which should be held in a directory hierarchy where it will be
> once its content has been expanded to contain executable Java code. It
> should contain:
>
Most developers are likely guilty of writing code that could use some comments without putting in comments. Often we forget, sometimes we just don't know what others might want to know about, real peer reviews would be helpful there. We create git policies that say every merge must be reviewed by someone, then the reviewers are like yeah that looks fine, approve; and we don't get much if any feedback if they really understand, usually because we're coding in teams where everyone is rushing to code and taking time to tell if someone else's code is understandable doesn't seem like an acceptable use of time we could spend writing more code.
There is a best practice for unit tests that say write code stubs with unit tests before writing actual code, though they normally end up as an afterthought if the project is given a requirement to have tests.
I think all code should have comments though I normally put them in as an afterthought if I remember to do them at all, if it doesn't add them for me. I like having at minimum a code block at the top of every class stating who created it when.
0 new messages