|
Hello,
I have seen a lot of people add docs to their code but a lot of the time it isn't really useful information. This will explains what documenting is and some examples of good vs bad styles. Hopefully, you will have a better understanding of how to write effective documentation.
Documentation is text that you write to explain why an artefact is there, what it does and how to operate it.
Here's an example of documentation (going to refer it to rsps for your sake):
The docs are not that bad, it's clear why it exists, how we can use it including some additional information.Code:/** * This method sends a message to a player in their chatbox. * We have this to give general information to a player. * * Message are Strings and can be styled using the following: * @str@ - Adds a strike through the text * @red@ - Makes the colour appear red * @gre@ - Makes the colour appear green * @blu@ - Makes the colour appear blue * @bla@ - Makes the colour appear black * @yel@ - Makes the colour appear yellow * * An example useage of adding styles: "@red@Hello @whi@World" * This will make 'Hello' red and 'World' white. * * Please note: Messages cannot be longer then 255 characters in length. If the message is longer * than the 255 length limit, only 0-255 will be displayed and the rest of the message will be discarded. * * @param player - The player we are sending the message to. This cannot be null. * @param message - The formatted message to display to the player */ public void sendMessage(Player player, String message) { ... }
Here is an example of bad documentation:
This is unclear and doesn't telll us why we have it there.Code:/** * The username of the player */ private String username;
Instead something like this is better:
Please note these are all examples (the username example is just for concept). It is there to explain the whole concept of writing documentations.Code:/** * A username is what players use to identify each other. * Players use this name to login to the game and it is also * what other players see as their display name. * * Usernames are unique and there cannot be more then 1 person with the same * name. Please note: The length of a name must be between 1-12 characters. */ private String username;
You can see more examples by looking at the Java Documentations.
Hope this helps.
I don't see how's that being any better, you don't have to go with useless and obvious details with any documentation, actually, stating that the username is the username of the player
is better infact, as it simply gives you the point of it and its usage should be obvious.
Anyways, thanks for this.
If I want to document my code, I'll document it how I want to tbh.
It's just an example. If we had the following:
String username;
String displayName;
Then it would be right to document it properly. Nothing is obvious to an outsider lol - But yeah you're right - if it's really obvious then don't bother.
The username example was just something top of my head.
/* Constructs a new X */
public X() {...}
^ That's cringe.
Documenting vs commenting, is there a difference?
Comments should only contain useful, relevant information.
It's better to not have a comment than a useless, repetitive or outdated one.
Referring to your first example I would say
andCode:/** * This method sends a message to a player in their chatbox. * We have this to give general information to a player.
are useless comments because you can get the same information from reading the method and parameter namesCode:* @param player - The player we are sending the message to. This cannot be null. * @param message - The formatted message to display to the player */
I was meant to remove 'comments' from the op since I didn't want to talk about that. My bad
My sendMessage example and your reasoning isn't something I agree with.
The whole 'send message' is pretty abstract. You can understand that Player is obviously the player we are interacting with. String message - sure we know the message is a String data type. But without the docs the method would look like:
public void sendMessage(Player player, String message) {..}
If we don't inspect the code; what would you assume? Game message? Private message? A programmer might get confused with https://en.wikipedia.org/wiki/Message_passing ?
public void sendMessage(Player player, byte b) {...}
^ What do you think the above method might do?
The reason I am addressing the whole doc ur code properly is because I have seen some code that I have no idea what it does. The documentations didn't add clarity and so I ignored the code.
if you're going to release open-source software you should always document your code no matter how obvious it is because you can generate reference API's for people who may want to use it.
e.g
Netty API Reference (4.1.9.Final)
https://google.github.io/guava/releases/18.0/api/docs/
Instead of saying
You would be best off stating that an exception is thrown if the Player is null. The same can be said forCode:/** @param player - The player we are sending the message to. This cannot be null. */
as an exception would allow whoever was incorrectly using the API to be alerted of their mistakes.Code:/** Please note: Messages cannot be longer than 255 characters in length. If the message is longer than the 255 length limit, only 0-255 will be displayed and the rest of the message will be discarded.*/
Also, IMO, self documenting code and proper encapsulation are better alternatives to over-documentation and a lack of encapsulation.
« Previous Thread | Next Thread » |
Thread Information |
Users Browsing this ThreadThere are currently 1 users browsing this thread. (0 members and 1 guests) |