add Javadoc comments for methods in problems

[dbc2201]

Would it be okay to add JavaDoc comments for the methods for the problems, like the JavaScript track has?

[jmrunkle]

I have no problem with that, it will just take a significant amount of work to backfill it for all of the existing exercises. Perhaps focus on the concept exercises first?

[mirkoperillo]

As @jmrunkle said I'm also worried about the amount the work to do. What benefit do you think the comments on method can bring to students @dbc2201 ?

[dbc2201]

Hi @mirkoperillo @jmrunkle ,
I believe JavaDoc comments are an integral part of the language features we haven't tapped into yet. It would give the users the benefit of not having to switch back and forth between the instructions and the code when working in the CLI mode whether in a notepad-like editor or even a full-blown IDE. Plus, the JetBrains' IntelliJ IDE even has reader mode support to show the documentation-style comments as simple text when turned on. We could start by writing instructions for the tasks into JavaDoc comments first (which, to me, already feel like reading JavaDoc).
I understand this would be a huge undertaking and a lot of people might not be up for it, but I'm willing to do it, starting with the concept exercises first.
We could even have a mini-survey for this in Slack space if you would like to weigh in their opinion as well.

[jmrunkle]

To be clear, duplicating the instructions into the Javadoc is a bad direction to go in since they will certainly drift. As such the benefit of "not flipping back to the instructions" seems like a non-goal here.

That being said, Javadoc is a useful thing in general and does have advantages. Among other things, it fills gaps not explained by the method declaration itself. For example, it can describe side effects, or what the return values mean, or how a particular parameter is expected to be modified, or what situations cause some exception to be thrown. These types of things seem useful to add to Javadoc.

So, if your plan is to just duplicate the instructions markdown, I am opposed. But if you want to add descriptive Javadoc to the methods, I have no problem with that. It will still be quite a bit of work to add, but could be done incrementally.

[dbc2201]

Yeah sure, let's do that. I have felt the need for corner cases in the instructions sometimes. Let's try to add some descriptive JavaDoc to the methods.

[github-actions[bot]]

This issue has been automatically marked as action/stale because it has not had recent activity. Please update if there are new updates to provide.

[Metallifax]

Just curious if a consensus has been reached on this or if it's a no go. This sounds like a good first issue and something I can make regular changes to if it's still on the table.

[dbc2201]

Just curious if a consensus has been reached on this or if it's a no go. This sounds like a good first issue and something I can make regular changes to if it's still on the table.

I would love to help out!

[Metallifax]

@dbc2201 I'm on the road doing work things at the moment, but is there a chat channel we can use to coordinate?

[dbc2201]

@Metallifax sure, the chat channel works for me. :)

[dbc2201]

@Metallifax sure, the chat channel works for me. :)

My username is the same there as well @dbc2201

[Metallifax]

@dbc2201 Can't seem to find any official chat channel, I assumed gitter and sent you a message on there. Any chat platform you prefer?

[kotp]

To be clear, and to provide unambiguous information, I believe you assumed https://gitter.im/exercism/java and left a message there.

[Metallifax]

@kotp My bad, I meant that I reached out via DM on gitter. Thanks for pointing this out.

[github-actions[bot]]

This issue has been automatically marked as action/stale because it has not had recent activity. Please update if there are new updates to provide.

[sanderploegsma]

Just curious if a consensus has been reached on this or if it's a no go. This sounds like a good first issue and something I can make regular changes to if it's still on the table.

From what I gather from the comments here the consensus is: adding Javadoc comments to the starter implementations sounds like a good idea, as long as the comments add useful information for students that is not yet covered by the exercise instructions.

I would like to stress that adding Javadoc comments for the sake of having Javadoc comments is not a good idea. I've seen so much code littered with comments because the developers 'had to' that end up like this:

/**
 * The FileOutputWriter class writes output to a file.
 */
public class FileOutputWriter {
    /**
     * The file to write to.
     */
    private final File outputFile;

    /**
     * Creates a new FileOutputWriter with the given file.
     * 
     * @param file The file to write to.
     */
    public FileOutputWriter(final File file) {
        this.outputFile = file;
    }

    /**
     * Writes the given output to the file.
     * 
     * @param output The output to write to the file.
     */
    public void writeOutput(String output) {
        // ...
    }
}

IMO this wouldn't add any useful information for students at all.

I think the best way forward here would be to gather a few examples of exercises that would actually benefit from having Javadoc in the starter implementation. From there we might be able to extract a new policy going forward, and backfill the exercises that already exist.

[sanderploegsma]

Closing this due to inactivity.