• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Too Many Comments?

 
Rancher
Posts: 425
Android Eclipse IDE Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I had recently applied at a relatively small but well known MNC who are into IT consulting, majorly on Agile methodologies.

As a part of the interview process, the candidates have to solve one out of two coding problems given by the company. I was also given two such coding problems and solved one of them. After a week from the day I submitted the code, I received a negative reply from them. They also provided their feedback for the code.

The feedback had 2 comments, one of which was "Too Many Comments. More comments than code." I was very surprised by this comment. I always thought the code should be well documented with comments, which is what I had done. I had provided about 2-3 lines class level comments for the main class and 1-2 lines for the other classes. And I had provided 1-2 lines comments for each method. I'm not sure if this would classify as "Too many comments" or "More comments than code".

So, the question is, is it bad coding practice to provide comments for every class, method, etc.? I would really appreciate anyone's input, since I have always practiced coding with comments, assuming it contributes to a better code.

-Pushkar
 
Ranch Hand
Posts: 49
Spring Redhat Clojure
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks for the "master" coders who "fail" to write comments in legacy applications!
Well writing comments in code won't make it any better but more readable, hence helping programmers/support engineers "inherit" it with ease.
I support writing comments!
 
Bartender
Posts: 6663
5
MyEclipse IDE Firefox Browser Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
It depends on what 'too many' implies for a developer. Here is what I usually do

* A class needs a few words describing what it does.

* Each public method need about a line of comment describing what it does.

* I refrain from providing comments inside methods. When I do provide them its usually not more than a line and it denotes how the control flows. Something like



I try to provide very descriptive method names and variable names instead of comments. So there are times when my variable names are longer than necessary. My definition of long is 20-30 characters. Public static constants are usually as long as that, if not longer.

The reason I dislike too many comments is that developers never update them. Here is a story...

I used to work on a code base with a lot of comments. It was unstable. In a meeting, the team was discussing with an architect about EJBs and performance and HTTP calls etc etc related to the code called by a method. I didnt understand why they were doing this since the code never makes an EJB call. But I decided to keep quiet thinking someone in the meeting knew something that I didnt. After the meeting was over I asked 'So why are you guys discussing EJBs ?'. One of the devs told me 'Well look, it says here on top of the method that it makes an EJB call to EJBX.' It turned out that EJBX did not exist and no EJB calls were made from the code.

The other reason I do not like lots of comments is because it breaks the way I read code. I scan the code and misplaced / misused comments distract me.

No comments in code is as bad as too many comments. But how many are necessary is subjective and also depends on the complexity of the code in question. So while there is no general answer to the question you raised, the views represented above might help you find out why your reviewer thought there were too many comments. Or perhaps your reviewer needs to redefine what 'too many' is.

So what was the other comment ?

[Edit]

Corrected spelling
 
Ranch Hand
Posts: 597
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
In IMO, when you write a code, you have to see how easy/difficult would be for new person to understand it. It depends how complex/easy the project/module/code is and your comments should be according to that. Focus should be when a new person comes, he/she should be able to understand it, but it should not be too much to maintain. Is too many comments is problem? IMO your code is should not look replacement for other documentation. Many things can be understood with naming conventions as Deepak said. But comments should be included where they are needed but they are not replacement for other documentation.
 
Ranch Hand
Posts: 1704
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I will try to provide as much comments as possible for all public methods/variables so that its easier to reuse the code for other developers.

I will try to avoid as much comments as possible in inline with code. Preferably you variable & method name conventions should self explanatory to understand the code. I will provide inline comments in scenarios like: reasons explain when some code is odd, to explain complex logic, when done some hard coding etc.,

 
Pushkar Choudhary
Rancher
Posts: 425
Android Eclipse IDE Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ok. Maybe I didn't mention clearly. Let me try once more.

My code did not have ANY comments inside a method. When I talking about comments, I was referring to the class-level and method-level comments which describe what that class or method does. Something like this:

Apart from this, there were no comments inside any methods.
 
Sandeep Awasthi
Ranch Hand
Posts: 597
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I personally would not like plain get and set methods to have comment because they are standard java bean conventions and should be understood.

[edit] If it is private method contains some logic and not java bean public get/set method, please ignore my above comments.
 
Sheriff
Posts: 10445
227
IntelliJ IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Pushkar Choudhary wrote:

My code did not have ANY comments inside a method. When I talking about comments, I was referring to the class-level and method-level comments which describe what that class or method does. Something like this:

Apart from this, there were no comments inside any methods.



That certainly does not fall under "Too many comments" category. Some might debate that getter/setter do not merit a javadoc. But I usually, make it a point to even have javadocs for such methods. That cannot be considered a bad practice.


They also provided their feedback for the code.

The feedback had 2 comments, one of which was "Too Many Comments. More comments than code."



If they are open to discussions, maybe ask them why they consider this a bad practice and how does it qualify as "too many comments". I guess they are just concentrating on the number of lines in that getter/setter method and then comparing it with the number of lines of javadoc comment. The "more comments than code" itself is a debatable topic. I personally find it useful to add as much comments (javadoc or code comments) as possible, so that some one else doesn't have to fight hard to understand why a particular piece of code exists.

 
Kj Reddy
Ranch Hand
Posts: 1704
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Pushkar Choudhary wrote:Ok. Maybe I didn't mention clearly. Let me try once more.

My code did not have ANY comments inside a method. When I talking about comments, I was referring to the class-level and method-level comments which describe what that class or method does. Something like this:

Apart from this, there were no comments inside any methods.



Sorry. In my view the JavaDoc comments do not fall under "Too many comments" including JavaDocs for getter/setter methods. JavaDocs are quite useful to understand what the public method/variable will do without looking into the source code.

Ask them if they can provide more details on the feed back by providing them your opinion.

 
Deepak Bala
Bartender
Posts: 6663
5
MyEclipse IDE Firefox Browser Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Ask them if they can provide more details on the feed back by providing them your opinion.



Do note that they may not respond back. I agree with Reddy that you should squeeze as much info as possible. But you may not get it.



That is fine except for 2 things

1. This is a private method. Javadocs for public methods usually derive more benefit, but this is not true all the time.
2. One could argue that setter methods do not need javadocs.

These are just observations. I am not arguing to or for them. But calling this 'too many comments' is not justified. Too many comments is something like this

 
Sandeep Awasthi
Ranch Hand
Posts: 597
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Well this is not too many comments. This is something else
 
Ranch Hand
Posts: 1374
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

JavaRanch Granny wrote:Debug only code - comments can lie.



When functionality changes, you are bound to change the comments as well. And If too many comments too much burden.
 
Marshal
Posts: 79151
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
If your functionality changes are requires a change in the documentation comments, then you are altering the public interface of your class and probably "breaking" other code
 
Ranch Hand
Posts: 144
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
There is some thought that code should be self describing, and not need a comment.








 
Author
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Pushkar Choudhary wrote:Ok. Maybe I didn't mention clearly. Let me try once more.

My code did not have ANY comments inside a method. When I talking about comments, I was referring to the class-level and method-level comments which describe what that class or method does. Something like this:

Apart from this, there were no comments inside any methods.


I actually have a few issues with this code/comment snippet.

1) It's *not* a simple setter, but:
    a) doesn't explain why not,
    b) violates JavaBean naming conventions meaning it may not even be *usable* as a setter in some circumstances,
    c) doesn't follow fluent interface naming convention ("logfile(path)")
2) It's not actually named what it does--I'd expect it to take a File, not a String. Why not name it setLogFilePath (or setLogfilePath, or...)
    a) and the method comment says it sets the name, but the parameter is called "path": which is it? Is it relative? Absolute? Depends on...?
3) Javadoc will automatically extract parameters. There's no reason to add a @param tag if it provides no additional information not provided by naming, so:
    a) private String setLogFilePath(String path) or (String thePath) is plenty of info.

Since it *does* violate JavaBean conventions, I have less of an issue with the @return tag, but that could just as easily be written as part of the method comment:So my issues aren't precisely that there are "too many comments", but rather they're not consistent with names, not consistent with convention (with no reason provided as to why), and with better naming, they become redundant at best, and just another potential maintenance failure at worst.

The comments themselves might not be enough for me to reject the code, but I *would* have to think twice about the naming conventions, depending on the larger context--I can't *really* say anything useful without having more context.

This is a particularly interesting question to me because my current interviewing process also includes a take-home coding exercise and I need to evaluate what's given back to me. I expect it will be interesting, if time-consuming. And I *definitely* have strong preferences about code, code style, commenting style, etc. which probably don't match with a lot of other peoples' ideas of what's "right".
 
David Newton
Author
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Mike Isano wrote:

Even better, for me, would bebecause then isPassingScore is testable in isolation, *and* eliminates the need for a comment.

(And depending on context, I might use a scoring implementation for that as well, or allow a dynamic formula... 'cuz that's just how I am.)
 
You ought to ventilate your mind and let the cobwebs out of it. Use this cup to catch the tiny ads:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic