Welcome to the Java Programming Forums


The professional, friendly Java community. 21,500 members and growing!


The Java Programming Forums are a community of Java programmers from all around the World. Our members have a wide range of skills and they all have one thing in common: A passion to learn and code Java. We invite beginner Java programmers right through to Java professionals to post here and share your knowledge. Become a part of the community, help others, expand your knowledge of Java and enjoy talking with like minded people. Registration is quick and best of all free. We look forward to meeting you.


>> REGISTER NOW TO START POSTING


Members have full access to the forums. Advertisements are removed for registered users.

Results 1 to 11 of 11

Thread: Overzealous Commenting?

  1. #1
    Member OA-OD-JD1's Avatar
    Join Date
    Jan 2012
    Location
    Australia
    Posts
    69
    My Mood
    Inspired
    Thanks
    9
    Thanked 1 Time in 1 Post
    Blog Entries
    29

    Default Overzealous Commenting?

    Hi everyone,

    I think this is more specific to programming in general, but I was wondering what the general protocol with commenting is for Java developers? I've been told that, in the industry, people don't appreciate your work if you have twice as many comments as actual code. In my limited programming experience, I'm guilty of overzealous commenting.

    What would you recommend as a safe amount of comments? By this I mean, including short comments at the end of important lines of code? Or inserting big blocks of text to fully explain your logic in doing something?

    Thanks,
    JD1


  2. #2
    Forum Squatter newbie's Avatar
    Join Date
    Nov 2010
    Location
    North Wales
    Posts
    661
    My Mood
    Stressed
    Thanks
    28
    Thanked 115 Times in 106 Posts
    Blog Entries
    1

    Default Re: Overzealous Commenting?

    Myself, If I'm writing code for learning purposes, I write a minimal amount of comments, even though I know I won't have a clue what I was trying to do when I look back in a few months time.
    Simply a small brief above a method saying what its used for.

    When I'm doing projects where I need to collaborate though, I always try and properly write up complete and clear comments which will be used for Java-Docs.
    Never bother with commenting variables though, unless they've got an uncommon declaration such as volatile etc.
    Please use [highlight=Java]//code goes here...[/highlight] tags when posting your code

  3. #3
    Member OA-OD-JD1's Avatar
    Join Date
    Jan 2012
    Location
    Australia
    Posts
    69
    My Mood
    Inspired
    Thanks
    9
    Thanked 1 Time in 1 Post
    Blog Entries
    29

    Default Re: Overzealous Commenting?

    Quote Originally Posted by newbie View Post
    Myself, If I'm writing code for learning purposes, I write a minimal amount of comments, even though I know I won't have a clue what I was trying to do when I look back in a few months time.
    Simply a small brief above a method saying what its used for.

    When I'm doing projects where I need to collaborate though, I always try and properly write up complete and clear comments which will be used for Java-Docs.
    Never bother with commenting variables though, unless they've got an uncommon declaration such as volatile etc.
    Hey newbie,

    Thanks for replying. You wouldn't happen to have an example handy of a collaborative piece would you? I just don't want to go over the top again. My IPT teacher at school once got upset with me for using too many comments and said that it's actually shunned in the industry. I want to get an idea of a good, safe, but not over-the-top amount of comments.

    Thanks,
    JD1

  4. #4
    Forum Squatter newbie's Avatar
    Join Date
    Nov 2010
    Location
    North Wales
    Posts
    661
    My Mood
    Stressed
    Thanks
    28
    Thanked 115 Times in 106 Posts
    Blog Entries
    1

    Default Re: Overzealous Commenting?

    Here are a few of the smaller methods I could find from a past project:

        /**
         * Evaluates the existance of a user by checking client cookies
         * @param context The <code>FacesContext</code> for the current request
         * @return <code>true</code> if a user Session key exists
         */
        public boolean doesUserExist(FacesContext context) {
            ExternalContext extContext = context.getExternalContext();
            return (extContext.getSessionMap().containsKey("Session_Key"));
        }

        /**
         * Determines if the request is to view the Login page or a secure page.
         * @param context the <code>FacesContext</code> for the current request
         * @return <code>true</code> if the path isn't a Login page request
         */
        public boolean isSecureContentRequest(FacesContext context) {
            ExternalContext extContext = context.getExternalContext();
            String path = extContext.getRequestPathInfo();
            return ((!"/Login.xhtml".equals(path) && (!extContext.getSessionMap().isEmpty())));
        }

    For larger more complex methods, simply image that with more @param tags are a larger but still concise description. Again, I think you should comment based on your own judgement, where you believe there could be confusion if someone was to look at your code with no explanation.
    Why waste time writing comments like:

     
    		/**
    		 * Returns a String containing a client's username
    		 * for the purposes of logging someone into a system :)
    		 * @return a String which stores a username
    		 */
    		public String getUsername() {
    			return userName;
    		}

    when what is says is meaningless and gives as much information as you can get from reading the method name.
    I'm sure many people will have their own views.
    Please use [highlight=Java]//code goes here...[/highlight] tags when posting your code

  5. The Following User Says Thank You to newbie For This Useful Post:

    OA-OD-JD1 (January 25th, 2012)

  6. #5
    Administrator copeg's Avatar
    Join Date
    Oct 2009
    Location
    US
    Posts
    5,307
    Thanks
    181
    Thanked 824 Times in 767 Posts
    Blog Entries
    5

    Default Re: Overzealous Commenting?

    As pointed out, you should at least add javadoc comments
    How to Write Doc Comments for the Javadoc Tool
    If you want a good idea of comments from a collaborative project, you should simply see the java API - all the text are comments, created by the javadoc tool, and the code is open source (meaning you can see the non-javadoc comments). You should also read the section regarding comments in the java code conventions guide:
    Code Conventions for the Java Programming Language

  7. The Following User Says Thank You to copeg For This Useful Post:

    OA-OD-JD1 (January 25th, 2012)

  8. #6
    Member OA-OD-JD1's Avatar
    Join Date
    Jan 2012
    Location
    Australia
    Posts
    69
    My Mood
    Inspired
    Thanks
    9
    Thanked 1 Time in 1 Post
    Blog Entries
    29

    Default Re: Overzealous Commenting?

    Thanks guys. I used to comment literally every line. I realise that's probably not useful at all. Thanks newbie for providing some examples, that's helped me out a lot. copeg, I'll be sure to check out those documents. Cheers.

  9. #7
    Member mjr's Avatar
    Join Date
    Jan 2012
    Location
    127.0.0.1
    Posts
    36
    My Mood
    Fine
    Thanks
    8
    Thanked 2 Times in 1 Post

    Default Re: Overzealous Commenting?

    I agree with the above about JavaDoc.

    As someone who is relatively new to Java myself, I'm still learning about how powerful JavaDoc can be.

    That said, I read somewhere (I forget where) that your code should "comment itself". In other words, people should essentially be able to look at your code (with minimal comments) and tell what it is doing, and what the intent of the code writer is/was. And that comments should mostly be used for code that may be ambiguous or difficult to decipher.

    Although I do think it might be helpful for a "return" on a method to have a comment, i.e. "This returns the result of the equation."

  10. #8
    Super Moderator Norm's Avatar
    Join Date
    May 2010
    Location
    SW Missouri
    Posts
    20,592
    Thanks
    50
    Thanked 2,235 Times in 2,207 Posts

    Default Re: Overzealous Commenting?

    I often use comments as a guide for coding. I design a method, write the comments saying what its going to do and then write the code as described in those comments.

  11. #9
    Member OA-OD-JD1's Avatar
    Join Date
    Jan 2012
    Location
    Australia
    Posts
    69
    My Mood
    Inspired
    Thanks
    9
    Thanked 1 Time in 1 Post
    Blog Entries
    29

    Default Re: Overzealous Commenting?

    Quote Originally Posted by Norm View Post
    I often use comments as a guide for coding. I design a method, write the comments saying what its going to do and then write the code as described in those comments.
    So you write the comments before actual Java code? I've never heard of that before. Does it work well?

  12. #10
    Super Moderator Norm's Avatar
    Join Date
    May 2010
    Location
    SW Missouri
    Posts
    20,592
    Thanks
    50
    Thanked 2,235 Times in 2,207 Posts

    Default Re: Overzealous Commenting?

    The idea is you design the code BEFORE writing the code.

    Of course I add comments later.

  13. #11
    Member OA-OD-JD1's Avatar
    Join Date
    Jan 2012
    Location
    Australia
    Posts
    69
    My Mood
    Inspired
    Thanks
    9
    Thanked 1 Time in 1 Post
    Blog Entries
    29

    Default Re: Overzealous Commenting?

    I suppose that would be a good way to organise your head. If you're a visual learner, you'll be able to see exactly what needs to be done and where.

Similar Threads

  1. Commenting in Java
    By djl1990 in forum Java Theory & Questions
    Replies: 2
    Last Post: October 26th, 2011, 12:15 PM
  2. Why no emphasis on commenting
    By Norm in forum The Cafe
    Replies: 2
    Last Post: July 25th, 2011, 07:53 AM
  3. Mastermind commenting help needed! :)
    By Mahela in forum What's Wrong With My Code?
    Replies: 2
    Last Post: February 28th, 2011, 02:55 PM