2

I am new to programming/Java and have been trying to teach myself it the last couple of weeks using some free textbooks and online resources. I thought a good way to learn would be to build a role-laying game I enjoy into a Java program. That being said, I know lots of people don't document their code effectively and want to avoid this being a habit, so I am trying to document everything in as much detail as possible. I cannot figure out if I am documenting this correctly though, even when referencing the Javadoc page, so any help would be appreciated. Basically I have a class 'Character' which implements all the required aspects of a character in this game. As an examplle, I have an enum which is a list of possible ability scores for a character in the game:

/**
 * AbilityScores is an enum type containing all the possible ability scores in the game. It is
 * utilized by the HashMap {@link #abilities} for the keys with an int being used as the values.
 */
private enum AbilityScores {
    STRENGTH,
    DEXTERITY,
    CONSTITUTION,
    INTELLIGENCE,
    WISDOM,
    CHARISMA,
    INSPIRATION,
    ARMOURCLASS
}

Then I have the corresponding HashMap:

 /**
 * abilities is a {@link HashMap} collection that contains {@link AbilityScores} as
 * keys and {@link Integer} as values.
 */
private HashMap<AbilityScores, Integer> abilities = new HashMap<AbilityScores, Integer>();

And then here is an example of my accessor method for a character's strength:

/**
 * This method returns a character's strength in the form of an integer.
 * @return strength as an integer.
 */
public int getStrength() {
    return abilities.get(AbilityScores.STRENGTH);
}

Am I documenting this correctly or have I incorrectly used '@link' etc. I did find some examples but I wasn't 100% sure as I couldn't find an example (apologies if there is one) where it showed an entire one start to finish like this one.

Any input or guidance is appreciated! Thank you

Fresh
  • 87
  • 7
  • 1
    The IDE should help you with this. Or you can run the javadoc command. – Patrick Dec 19 '18 at 21:32
  • Since the Java doc will form complete sentences when formatted, please start all of your documentation with a capital letter. There's some room for debate here but in the long run I think just using regular sentence grammar is the best. – markspace Dec 19 '18 at 21:36
  • Here's some info on how to use @link. Normally I just use {@code when I want to refer to class names. https://stackoverflow.com/questions/5915992/how-to-reference-a-method-in-javadoc – markspace Dec 19 '18 at 21:38
  • @markspace thanks for this. That link is very detailed and I'll be sure to reference it and corresponding documentation. – Fresh Dec 19 '18 at 21:44
  • Also, a strong +1 on "get your IDE to help you here". If you're not using an IDE: definitely start using one, or use a dedicated code editor with plugins for doing this for you. You should not have to guess at whether you're doing it right, your tooling should allow you to "obviously" do the right thing. – Mike 'Pomax' Kamermans Dec 19 '18 at 22:13
  • Another thing to consider is following Java naming conventions. Class names start with capital letters; it should be `AbilityScores`. – Slaw Dec 20 '18 at 00:51
  • yes thanks @Patrick also for the IDE recommendation. – Fresh Dec 20 '18 at 00:57
  • @Slaw it is an enum within the class 'Character'; I think I mentioned it in the original question, but apologies if it wasn't clear. – Fresh Dec 20 '18 at 00:58
  • Enums are a special type of class. Classes, enums, interfaces, and annotations all follow the same naming convention. – Slaw Dec 20 '18 at 00:59
  • @Slaw thank you! This is exactly the kinda gotcha I am looking for! Fixed in my code – Fresh Dec 20 '18 at 01:00
  • Hold on, you've got a class called `Character`? Do you realise that the standard Java API also has a class called `Character`? – DodgyCodeException Dec 20 '18 at 16:52
  • @DodgyCodeException that's fine. Its Java so if I am using my Character class I'll simply write the fully qualified path for import/use. As far as I am aware, and based on a multitude of research, there is no convention in Java that states you should not duplicate class names, especially when their functionality is not even remotely similar. This question addresses this specific case: https://stackoverflow.com/questions/2079823/importing-two-classes-with-same-name-how-to-handle – Fresh Dec 21 '18 at 02:27
  • That's ok. There's no convention, and it's easy to remove the ambiguity, but it can be an inconvenience sometimes. E.g. in every class in the same package as your Character class, you will have to use `java.lang.Character.toUpperCase(c);` instead of just `Character.toUpperCase(c);` (though even that one can be statically imported). It's a more obvious inconvenience when you name your class something that's more widely used, such as `String`. – DodgyCodeException Dec 21 '18 at 10:30

0 Answers0