[Zekorov]

Why don't people comment more in their code? I'm kind of a noob still at programming and when i'm looking at things to help people on in the java programming forum, sometimes i have no idea why the coders did what they did in their code because i don't understand many things in Java yet. However, when you comment in your code, and tell what each line or few lines is doing, it helps people like me understand better what's going on, so we'll have more of a chance to help you. But every time i look at code to help someone, there are no comments anywhere. it's aggravating to me. Anyone else have thoughts on this?

p.s. Sorry if i posted in the wrong forum... i figured since this was java programming related i should put it here.

oh and sorry one more thing, the people that do comment in their code, are generally out of my league of helping haha

This post has been edited by Zekorov: 27 December 2010 - 04:24 PM

[xTorvos]

I believe that the general rule among professional programmers is that you don't comment as to 'what' something is doing, you comment as to 'why' you decided to do it that way. This is because you can expect that those who are reading your code are also professional programmers that understand what most commands/syntax does.

That being said, when students comment their code, they usually do so sparsely because they forget to or don't understand when code needs commented.

[Dogstopper]

I think this is better suited for the Corner Cubicle forum, since commenting is inherently cross-language.

My take on it is frequently, well designed variable names, class names, and simple operations are self documenting, and there is just no need to comment. Too much commenting is worse than none at all as it restricts easy readability. No commenting (or bad self-documenting code) is also bad.

It's a precarious balance. Most of the time, I use comments to give Javadoc, copyright information, to explain really difficult to understand sections, and to make bug fixes.

[hookiethe1]

Commenting your own code adequately can be tough, because often it's something you've eaten/breathed/slept/deliberated over for some time, you know it intimately, and every part of it is familiar and obvious to you, as the write. If you haven't put any thought or deliberation into it, then it's probably a very simple piece of code that would also seem obvious to it's writer.
Good commenting requires putting yourself in the place of someone who has never seen this particular code before, and trying to come up with just the right amount of explanation so that they can understand it at it's highest level.

Pretty tough to do when it's your own code.

[Kilorn]

I've always looked at it like "Hey, it's my code, I'm the only one who is going to see it, so why would I need to comment the majority of the code since I'll just remember it." Then a few months later, or even a year or more later, you're required to go back to your old code for whatever reason and you find yourself thinking "wtf was I doing here?" and you end up wasting time having to relearn what you've coded and why you coded it that way. I try to comment my code as much as possible for this reason, not to mention if anyone else ever has to look at it.

[Zekorov]

hmmm.... This is true.... Personally I like to use comments where things need improvements, or where i have to fix something, and at every set of lines i use to do a specific task. that way i remember what the lines do if i need to like in my DoomGame program i've been working on forever. i have assorted comments where the onlooker could see why i've used what and where i used it. I also have comments in places that i feel are causing bugs and need fixing. or places that i just feel i will improve later on. But this brings me to a new thought; why don't we come up with guidelines for commenting? And i say guidelines, because that way people don't feel restricted to them because commenting is truly a subjective thing, but when people have programs others can't understand, we can't always assume the other person trying to understand is professionally adequate. For instance, a guideline could be set up like this:
Commenting Guideline

1. organize code into blocks, and above each block, tell what the main of the program is doing. (even though this is against tradition, it helps new programmers know what's going on)

2. Use comments where possible improvements are visible and tell what the possible improvements are

3. Use comments where bugs are located that way they become easier to locate and fix, for the author and other code readers.

4. use comments to explain more complex lines of code, and though redundant it is, for complex things, use specific comments for each line, telling what each line does to compliment the whole surrounding function.

and so on and so forth.
I don't know this is really just an idea. Probably not even really needed. But i like the idea of coming up with a good structure to use for commenting because commenting does really help the new guys like myself.

[dorknexus]

In the professional world, how and what you comment is defined on a per project basis for specifics. In general I have found that for OO programming I annotate classes and methods with comments. I also attach comments to pieces of code whose function I feel may not be obvious at a quick glance.

The purpose of commenting is to increase readability and ease of maintenance/re-factoring. Its important not to be too sparse with commenting but you must also avoid becoming to verbose.

As for an earlier post which stated they felt the "why" of code should be put into comments...I don't think the "why" questions should be answered in comments as those are 9 times out of 10 architectural questions. These should be left to documents concerning architecture and design rather than real implementation.

[JaKWaC]

I let my variables do the commenting for me in a lot of my code. If the variables are descriptive enough I don't need as many comments to explain whats going. As a lot of said, you have to expect people to understand the syntax of the language otherwise you'd spend more time commenting your code than writing it.

This post has been edited by JaKWaC: 28 December 2010 - 09:08 AM

[hookiethe1]

In my mind, if your code is well commented then you should be able to delete all the code and rewrite the program by looking at the comments. Not so much stuff like "increment X here" but things like "this function accepts () and returns ()" or "if this, then that, else that." I think it should be similar to a high level flowchart.

[JaKWaC]

If you did it that way, you'd be writing your program twice. I do agree with the function agurments and expected returns, but no need to write your entire program in sudo code.

[NeoTifa]

If you look at my code, it's 75% documentation, 25% code, and 100% bullshit.

[Zekorov]

JaKWaC, on 28 December 2010 - 11:12 AM, said:

If you did it that way, you'd be writing your program twice. I do agree with the function agurments and expected returns, but no need to write your entire program in sudo code.

That's true. like Dogstopper and several others stated, commenting in code is kind of like a balance beam. you don't want too much commenting, or too little. But, idk you should definitely try to comment on your stuff. no matter what it is. Although, if is correct, which i have no reason to not believe him, i would agree most definitely with his comment. it makes sense. Usually, your comments will be dictated by some main idea, or function for your code, thus, the comments alone will become their own little story with several parts skipped in between each one of them, and these parts are where the onlooker/ author has to fill in the blank with their own understanding of code, which is where all the story's details are. haha