Commenting in Code

it does help to understand your code

Page 1 of 1

14 Replies - 3262 Views - Last Post: 10 May 2014 - 11:54 AM

#1 Zekorov  Icon User is offline

  • D.I.C Head

Reputation: 22
  • View blog
  • Posts: 226
  • Joined: 16-May 10

Commenting in Code

Posted 27 December 2010 - 04:17 PM

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. :P

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


Is This A Good Question/Topic? 3
  • +

Replies To: Commenting in Code

#2 xTorvos  Icon User is offline

  • D.I.C Regular
  • member icon

Reputation: 61
  • View blog
  • Posts: 271
  • Joined: 23-October 09

Re: Commenting in Code

Posted 27 December 2010 - 04:23 PM

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.
Was This Post Helpful? 4
  • +
  • -

#3 Dogstopper  Icon User is offline

  • The Ninjaducky
  • member icon



Reputation: 2870
  • View blog
  • Posts: 11,021
  • Joined: 15-July 08

Re: Commenting in Code

Posted 27 December 2010 - 04:24 PM

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.
Was This Post Helpful? 3
  • +
  • -

#4 hookiethe1  Icon User is offline

  • D.I.C Lover

Reputation: 416
  • View blog
  • Posts: 1,335
  • Joined: 28-September 10

Re: Commenting in Code

Posted 27 December 2010 - 04:30 PM

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.
Was This Post Helpful? 3
  • +
  • -

#5 Kilorn  Icon User is offline

  • XNArchitect
  • member icon



Reputation: 1355
  • View blog
  • Posts: 3,528
  • Joined: 03-May 10

Re: Commenting in Code

Posted 27 December 2010 - 04:52 PM

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.
Was This Post Helpful? 0
  • +
  • -

#6 Zekorov  Icon User is offline

  • D.I.C Head

Reputation: 22
  • View blog
  • Posts: 226
  • Joined: 16-May 10

Re: Commenting in Code

Posted 27 December 2010 - 04:53 PM

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.
Was This Post Helpful? 0
  • +
  • -

#7 dorknexus  Icon User is offline

  • or something bad...real bad.
  • member icon

Reputation: 1255
  • View blog
  • Posts: 4,618
  • Joined: 02-May 04

Re: Commenting in Code

Posted 27 December 2010 - 05:41 PM

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.
Was This Post Helpful? 4
  • +
  • -

#8 JaKWaC  Icon User is offline

  • D.I.C Head

Reputation: 76
  • View blog
  • Posts: 234
  • Joined: 15-November 10

Re: Commenting in Code

Posted 28 December 2010 - 08:42 AM

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

Was This Post Helpful? 0
  • +
  • -

#9 hookiethe1  Icon User is offline

  • D.I.C Lover

Reputation: 416
  • View blog
  • Posts: 1,335
  • Joined: 28-September 10

Re: Commenting in Code

Posted 28 December 2010 - 09:06 AM

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.
Was This Post Helpful? 0
  • +
  • -

#10 JaKWaC  Icon User is offline

  • D.I.C Head

Reputation: 76
  • View blog
  • Posts: 234
  • Joined: 15-November 10

Re: Commenting in Code

Posted 28 December 2010 - 09:12 AM

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.
Was This Post Helpful? 0
  • +
  • -

#11 NeoTifa  Icon User is offline

  • Whorediot
  • member icon





Reputation: 2582
  • View blog
  • Posts: 15,604
  • Joined: 24-September 08

Re: Commenting in Code

Posted 28 December 2010 - 09:14 AM

If you look at my code, it's 75% documentation, 25% code, and 100% bullshit. :D
Was This Post Helpful? 2
  • +
  • -

#12 Zekorov  Icon User is offline

  • D.I.C Head

Reputation: 22
  • View blog
  • Posts: 226
  • Joined: 16-May 10

Re: Commenting in Code

Posted 28 December 2010 - 12:01 PM

View PostJaKWaC, 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. :D 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. :D haha
Was This Post Helpful? 0
  • +
  • -

#13 fiberoptck  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 7
  • Joined: 08-May 14

Re: Commenting in Code

Posted 10 May 2014 - 11:17 AM

Shouldn't it only be necessary to comment on your code when you have created something beautiful and it isn't all that simple to understand? I mean if you for instance have a set that is churning up multiple actions and its not all that clear by looking at it. So for the sake of sanity, you apply some comments to give someone whom might be attempting to debug an issue a better understanding?

I always took the concept of commenting as a debug rule for others that might be blowing up their application and can't understand why, they can refer to that comment and understand further what is going on in the code that might benefit and possible solve the issue.

I suppose its like reading Shakespeare. A avid reader and understanding of the language of Shakespeare would be able to dissect the reading quite easily. But for some, they needs some comments on the paragraph or line that helps them understand the reading a little more clearly than attempting to try to understand it with little or no guidance.
Was This Post Helpful? 0
  • +
  • -

#14 astonecipher  Icon User is offline

  • Major DIC Head
  • member icon

Reputation: 547
  • View blog
  • Posts: 2,441
  • Joined: 03-December 12

Re: Commenting in Code

Posted 10 May 2014 - 11:34 AM

I prefer to write self documenting code. When people debug, they tend not to both updating the comments unless they are new.

You can comment what the code should do and leave the logic to the code. That way the comment should stay current unless the spec changes.
Was This Post Helpful? 0
  • +
  • -

#15 Ntwiles  Icon User is offline

  • D.I.C Addict

Reputation: 148
  • View blog
  • Posts: 824
  • Joined: 26-May 10

Re: Commenting in Code

Posted 10 May 2014 - 11:54 AM

I comment the crap out of my code. Some people use it for explanation of strange algorithms, and I do too, but more often than not I use my comments for indexing. I'll explain in plain English even the simplest of algorithms, because its easier for me to skim through comments than code to quickly find the lines I'm looking for later.
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1