Thread: 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

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.

Originally Posted by newbie

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

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.

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

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.

Originally Posted by Norm

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?

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.