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

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

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

Show all headers | View raw

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.
> ...


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

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