Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #39797

Re: What Makes for Good Comments? (Part 3 of 4)

Show all headers | View raw

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

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

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