Documenting

[VisionSet]

I'm used to seeing and have adopted the javadoc style overtime so as to
document my packages/classes/methods from a responsibilities and contract
stand point. This makes total sense for the client programmer using library
code. However if you aren't writing library code and your main concern is
maintenance by yourself or whoever it seems to me that comments such as
'this method is known/written to be called by foo for reason x' have a
place.

Anyone any comments concerning this or can point to me examples of
documentation that exists for mainly maintenance purposes?

I realise that this is where sequence diagrams come it to there own.

TIA

 

[Chris Uppal]

However if you aren't writing library code and your main
concern is maintenance by yourself or whoever it seems to me that
comments such as 'this method is known/written to be called by foo for
reason x' have a place.

I may be reading too much into the specific example you have chosen, but I'd
say that for most purposes documenting where a method is called from, or where
a class is used, is counter-productive. If your support tools are any good at
all, then finding that kind of browsing information is easy.

Not that there aren't cases where the control-flow (or similar) is complicated
and requires explication, but I wouldn't expect that to be the typical case.
If it is required, then I'd either put it in the JavaDoc or in "normal"
comments, depending on who the JavaDoc is intended to be read by.

And, of course, there's always a need for comments intended only for the person
reading the code. Some people claim that well-written code is it's own
commentary (and I agree); some go on to claim that well-written code is all the
commentary that is needed -- they are deluding themselves.

-- chris

 

[VisionSet]

If your support tools are any good at
all, then finding that kind of browsing information is easy.

Yes, I should assume these are available since they are more powerful than
any snapshot comment I may make.
I'll not stray from the conventions.
Thanks all.

 

[Ed]

VisionSet skrev:

I'm used to seeing and have adopted the javadoc style overtime so as to
document my packages/classes/methods from a responsibilities and contract
stand point. This makes total sense for the client programmer using library
code. However if you aren't writing library code and your main concern is
maintenance by yourself or whoever it seems to me that comments such as
'this method is known/written to be called by foo for reason x' have a
place.

Anyone any comments concerning this or can point to me examples of
documentation that exists for mainly maintenance purposes?

I realise that this is where sequence diagrams come it to there own.

TIA

The advice given so far about being cautious of describing the type of
comment you suggest seems wise; this type, however, could be seen as
simple implementation comments, and as such Sun's style guidelines
recommend that these comments be placed after the class/method
declaration:

(From
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#16838)

"If you need to give information about a class, interface, variable, or
method that isn't appropriate for documentation, use an implementation
block comment (see section 5.1.1) or single-line (see section 5.1.2)
comment immediately after the declaration. For example, details about
the implementation of a class should go in in such an implementation
block comment following the class statement, not in the class doc
comment."

Yes, it's just a convention, and yes, they do take sides in the
open-curly-bracket-placement war which is enough to have some
programmers burning the convention in the streets, but ...

..ed

 

[bugbear]

I do put those sorts of comments into my code, but never in javadocs,
just as regular comments.

The client programmer should be able to work entirely from the
javadocs, but the maintenance programmer for the library will be
looking at the code anyway.

I like putting this kind of stuff in Javadoc;
javadoc is more hyperlinked than my source files/tree

BugBear

 

[Monique Y. Mudama]

I like putting this kind of stuff in Javadoc; javadoc is more
hyperlinked than my source files/tree

BugBear

It just feels like it violates the concept of encapsulation to put
details that only the implementer should care about in API-level
documentation.

 

[im]

It just feels like it violates the concept of encapsulation to put
details that only the implementer should care about in API-level
documentation.

You can generate your documetation with different javadoc parameters for
different purposes. For example you can include/exclude packages or only
show public methods and classes.

Imre

 

[Monique Y. Mudama]

The advice given so far about being cautious of describing the type
of comment you suggest seems wise; this type, however, could be seen
as simple implementation comments, and as such Sun's style
guidelines recommend that these comments be placed after the
class/method declaration:

(From
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#16838)

"If you need to give information about a class, interface, variable,
or method that isn't appropriate for documentation, use an
implementation block comment (see section 5.1.1) or single-line (see
section 5.1.2) comment immediately after the declaration. For
example, details about the implementation of a class should go in in
such an implementation block comment following the class statement,
not in the class doc comment."

Hey, neat! It turns out I've been following the Sun style guidelines
and didn't even know it!

 

[Monique Y. Mudama]

You can generate your documetation with different javadoc parameters
for different purposes. For example you can include/exclude packages
or only show public methods and classes.

Well, yeah, I suppose you can.

Okay, I admit it: I'm lazy!

 

[Roedy Green]

I like putting this kind of stuff in Javadoc;
javadoc is more hyperlinked than my source files/tree

private declaration Javadoc is a good place to put information for the
maintenance programmer not of interest ot clients of the package.

 

[Andrew McDonagh]

private declaration Javadoc is a good place to put information for the
maintenance programmer not of interest ot clients of the package.

True, though actually separating the API Interface from the
implementation, not only serves the same purpose, but will give us a
more flexible design.

Where possible, its always better to expose a public API via Interfaces,
than concrete classes.