Comments for a class that isn't an entity

Question

According to Java's commenting conventions, classes comments should describe a "thing", rather than "actions". It is easy when the class IS a thing (ex. a Clown), but what if it isn't?

In this case, the ShapeProvider is a proxy class that requests "stringified" Strings to a small server application via the get method. The string is then parsed to build a BaseShape object, that is returned to the client of the service. The client simply draws the shape on a small GUI. This is a school work, so I'd want my comments to be as close as possible to the Java conventions.

/** * How should I comment this? */ public class ShapeProvider extends ServerConnection{ /** * Method comment that is okay. */ public BaseShape get(){ //Requests the shape //Parses the response //Use a Factory to create an instance of BaseShape //Return it } }

If someone finds a better name for the question, don't hesitate to change it! — IEatBagels
– IEatBagels, Commented Jan 23, 2015 at 15:22
I think you need to provide more context. It's difficult to come up with documentation for something when we only have the class name and a method signature. — npinti
– npinti, Commented Jan 23, 2015 at 15:25
I'll edit! I was looking for a general guideline but if it isn't easy to figure I'll add more context to be more specific. — IEatBagels
– IEatBagels, Commented Jan 23, 2015 at 15:26
what is in Class/Interface Specification section of official Requirements for Writing Java API Specifications that you don't understand? FWIW word "thing" isn't mentioned there, where did you get that idea? — gnat
– gnat, Commented Jan 23, 2015 at 16:01

valenterry · Accepted Answer · 2015-01-23 15:30:55Z

But your ShapeProvider is a thing!

How comes, you don't see it as a thing? Your ShapeProvideris a someone who is responsible for providing you shapes while relying on X and Y to do so. I think that is a acceptable commentation regarding the commenting conventions.

But it shows you, that this code is actually not very well designed or named. Because why on earth would a ShapeProvider extend a ServerConnection? That's just wrong. A ShapeProviderrather relies on some repository or repository connection and uses it to create the shapes. extends should therefore not be used for this purpose at all!

Your answer made me realize that my ShapeProvider is a repository! But I should remove the server's connection code from that repository to put it somewhere else. Did I understand your answer correctly? — IEatBagels
– IEatBagels, Commented Jan 23, 2015 at 15:40
Make your repository not extending a connection but using it. Pass the connection into the constructor and let the repository tell its connection to fetch the information the repository needs to fullfill its tasks. — valenterry
– valenterry, Commented Jan 23, 2015 at 16:18

Stack Exchange Network

Comments for a class that isn't an entity

1 Answer 1

But your ShapeProvider is a thing!

Hot Network Questions

Comments for a class that isn't an entity

1 Answer 1

But your ShapeProvider is a thing!

Related

Hot Network Questions