Thread: A snippet on how to document your code!

Page 1 of 3 123 LastLast
Results 1 to 10 of 21
  1. #1 A snippet on how to document your code! 
    Registered Member
    Join Date
    Dec 2013
    Posts
    419
    Thanks given
    127
    Thanks received
    85
    Rep Power
    349
    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):

    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) {
     ...
    }
    The docs are not that bad, it's clear why it exists, how we can use it including some additional information.

    Here is an example of bad documentation:

    Code:
    /**
     * The username of the player
     */
    private String username;
    This is unclear and doesn't telll us why we have it there.

    Instead something like this is better:
    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;
    Please note these are all examples (the username example is just for concept). It is there to explain the whole concept of writing documentations.
    You can see more examples by looking at the Java Documentations.

    Hope this helps.
    Reply With Quote  
     

  2. Thankful user:


  3. #2  
    Software Developer

    Tyrant's Avatar
    Join Date
    Jul 2013
    Age
    24
    Posts
    1,562
    Thanks given
    678
    Thanks received
    423
    Rep Power
    1060
    Quote Originally Posted by Kiissmyswagb View Post
    Instead something like this is better:
    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;
    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.
    Reply With Quote  
     

  4. Thankful user:


  5. #3  
    ¯\_(ツ)_/¯


    Join Date
    Jul 2014
    Posts
    1,803
    Thanks given
    928
    Thanks received
    550
    Rep Power
    299
    If I want to document my code, I'll document it how I want to tbh.
    Reply With Quote  
     


  6. #4  
    Registered Member
    Join Date
    Dec 2013
    Posts
    419
    Thanks given
    127
    Thanks received
    85
    Rep Power
    349
    Quote Originally Posted by Tyrant View Post
    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.
    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.
    Reply With Quote  
     

  7. Thankful users:


  8. #5  
    Renown Programmer
    Greg's Avatar
    Join Date
    Jun 2010
    Posts
    1,179
    Thanks given
    260
    Thanks received
    1,012
    Rep Power
    2003
    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
    Code:
    /**
     * This method sends a message to a player in their chatbox.  
     * We have this to give general information to a player.
    and
    Code:
     * @param player - The player we are sending the message to. This cannot be null.
     * @param message - The formatted message to display to the player
     */
    are useless comments because you can get the same information from reading the method and parameter names
    Attached imageAttached image
    Reply With Quote  
     

  9. Thankful user:


  10. #6  
    Registered Member
    Join Date
    Dec 2013
    Posts
    419
    Thanks given
    127
    Thanks received
    85
    Rep Power
    349
    Quote Originally Posted by Greg View Post
    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
    Code:
    /**
     * This method sends a message to a player in their chatbox.  
     * We have this to give general information to a player.
    and
    Code:
     * @param player - The player we are sending the message to. This cannot be null.
     * @param message - The formatted message to display to the player
     */
    are useless comments because you can get the same information from reading the method and parameter names
    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.
    Reply With Quote  
     

  11. #7  
    Ex Rune-Scaper

    Join Date
    Jun 2008
    Posts
    3,534
    Thanks given
    457
    Thanks received
    1,257
    Rep Power
    990
    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/
    Reply With Quote  
     

  12. Thankful users:


  13. #8  
    SERGEANT OF THE MASTER SERGEANTS MOST IMPORTANT PERSON OF EXTREME SERGEANTS TO THE MAX!

    cube's Avatar
    Join Date
    Jun 2007
    Posts
    8,871
    Thanks given
    1,854
    Thanks received
    4,745
    Rep Power
    5000
    Quote Originally Posted by Ugly View Post
    If I want to document my code, I'll document it how I want to tbh.
    This is why rsps is a total mess

    Attached image

    Reply With Quote  
     


  14. #9  
    ¯\_(ツ)_/¯


    Join Date
    Jul 2014
    Posts
    1,803
    Thanks given
    928
    Thanks received
    550
    Rep Power
    299
    Quote Originally Posted by S Quare Quxx View Post
    This is why rsps is a total mess
    True but I don't really care if people can't understand my code, as long as I do it's fine by me
    Reply With Quote  
     

  15. #10  
    Registered Member
    hc747's Avatar
    Join Date
    Dec 2013
    Age
    26
    Posts
    1,474
    Thanks given
    3,312
    Thanks received
    691
    Rep Power
    1098
    Instead of saying
    Code:
    /**
    @param player - The player we are sending the message to. This cannot be null.
    */
    You would be best off stating that an exception is thrown if the Player is null. The same can be said for
    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.*/
    as an exception would allow whoever was incorrectly using the API to be alerted of their mistakes.
    Also, IMO, self documenting code and proper encapsulation are better alternatives to over-documentation and a lack of encapsulation.
    Reply With Quote  
     

Page 1 of 3 123 LastLast

Thread Information
Users Browsing this Thread

There are currently 1 users browsing this thread. (0 members and 1 guests)


User Tag List

Similar Threads

  1. How to Shorten your code using a for loop
    By cr3zzy in forum Tutorials
    Replies: 17
    Last Post: 12-08-2013, 06:21 PM
  2. Replies: 6
    Last Post: 08-22-2012, 03:56 PM
  3. Replies: 0
    Last Post: 03-20-2012, 09:25 AM
  4. Replies: 4
    Last Post: 09-14-2009, 02:29 AM
  5. [IMPORTANT] How to tidy your coding
    By Vastiko in forum Tutorials
    Replies: 10
    Last Post: 10-27-2008, 04:14 PM
Posting Permissions
  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •