[general] Commenting your own code?

[Pieman]

So I was wondering if people here comment there own code? I have a bad habit of never commenting anything unless I know it's gonna be read by other people. Though I tend to write pretty readable code.

Also, to the people who do comment there code, how do you comment it? Do you write a block comment on the beginning of your code explaining what it does or do you comment each line separately ?

 

[foxx]

I do never comment anything..

 

[-fedexer-]

Seems we both have the habit of not commenting our code, usually no-one else will be reading it, and i make it understandable, so i have never commented.

Though i likely will in the future, as it's best to get into the habit of doing it.

 

[danse]

So I was wondering if people here comment there own code? I have a bad habit of never commenting anything unless I know it's gonna be read by other people. Though I tend to write pretty readable code.

Also, to the people who do comment there code, how do you comment it? Do you write a block comment on the beginning of your code explaining what it does or do you comment each line separately ?

dear Pie commenting also has it standards, and it has it usability as well even if the code is for your eyes only. Imagine the situation you have made a huge CMS or whatever large projects, 2-3 years passed and know you've reminded yourself hey i have a CMS ready to use just when i need it. Now what the hell was the class XYZ for ? So you may write comments just to know after sometimes what is for what.
As for the standards usually people us same comment system as it comes with the UML.
example

<?php

error_reporting(E_ALL);

/**
 * My Example CMS - class.Controller.php
 *
 *
 * Automatic generated with ArgoUML 0.24 on 28.05.2008, 23:10:33
 *
 * @author Sample Programmist <[email protected]>
 */

if (0 > version_compare(PHP_VERSION, '5')) {
    die('This file was generated for PHP 5');
}

/**
 * include Config ( name the Class you include )
 *
 * @author Sample Programmist <[email protected]>
 */
require_once('class.config.php');

/**
 * include SQL
 *
 * @author Sample Programmist <[email protected]>
 */
require_once('class.sql.php');

/**
 * include Satelite
 *
 * @author Sample Programmist <[email protected]>
 */
require_once('class.satelite.php');

/**
 * include Sessions
 *
 * @author Sample Programmist <[email protected]>
 */
require_once('class.sessions.php');
/**
 * Short description of class Controller
 *
 * @access public
 * @author Sample Programmist <[email protected]>
 */
class Controller
{
    // --- ATTRIBUTES ---
	
	// if you would some attributes for the class example below
	
	public 	$mypublicVar 	= (int) 0;
	private	$myprivateVar 	= (string) 'asshole';
	static	$mystaticVar	= (boolean) true;

    // --- OPERATIONS ---

    /**
     * Short description of method __constuct
     * Description of the method
     * @access public ( accesibility )
     * @author Sample Programmist <[email protected]>
     * @return void ( return type, array ? boolean ? string ? integer ? etc )
     */
    public function konstruktor()
    {
		$this->dane 	= (object) satelite::retDane();
		$this->post 	= (object) satelite::retPost();
		$this->get		= (object) satelite::retGet();
		$this->files 	= (object) satelite::retFiles();
		$this->session	= (object) satelite::retSession();
    }

    /**
     * Short description of method igniteObject
     * Creates a new object requested by user with the specified method
     * @access public
     * @author Sample Programmist <[email protected]>
     * @return void
     */
    public function igniteObject()
    {
		$metoda	= $this->dane->metoda;
		$obj = new $this->dane->obiekt;
		$x = $obj->$metoda();
		return $x;
    }
} /* end of class Controller */
?>

Now please notice that those methods are just 3-4 lines, now imagine methods wich would contain like 300-400 lines, ain't it easier to see on the begning what it returns ? and what params it eats ? and they are for ? Than searching thru those 300-400 lines

Regards.

 

[Intelext]

I always comment my code because sometimes I don't code that program for months and then when I am back I don't understand anything of what I wrote there.

Usually my comments go like this:

//================================
//Some Text...
//================================

//Some text...

//================================
//================================
//=======Program by Intelext======
//================================
//================================

 

[Daevius]

Generally, I always think: will I understand what I do here after a few months? Sometimes not, so I'll add a few comments on the end of the line. If it's really easy to grasp if you look at it for a few seconds I don't comment it.

I really hate it to see that some people over-comment their code. Usually blocks of comments with all sorts of fancy things (like big ASCII characters etc.). Over-commenting takes away the original purpose of commenting: making it easier to grasp for someone. While if 80% of your code is comments, it would be a whole lot of scrolling and every line would be separate, rather then bundled together where needed.

If I let others use my code, I document it. Comments in your code is good (a few inline comments here and there), but the main part of your source code should be code...

It also depends on your code layout, indention and clustering lines that belong to eachother (too few for a function) usually help much more then some comment lines.

But thats me some people really like to see the Java comments DanseMacabre shows...I personally think that should be in an API / external documentation.

Mostly your code layout / set up is bad when you can't understand what's happening. (ASM not included...ASM simply needs comments on every line ^^)

 

[Madison]

Once you go and read someone else's code that is crazy, or messy or just now how you would write it, then you'll start to see why how and where you need comments. Sure doing things for yourself is one thing, but if you ever code for a job, or for someone else or ever intend to you need to learn how to make good decent comments in your code. Somethings require a LOT of comments, but some require only a short explain of why you are doing it a certain way.

Remember that everyone writes code just a bit differently in their own style, doesn't mean one is right or wrong necessarily, but a few comments can make a big difference.

Personally I think big text comments like Intelex's (sorry to pick on you) are really annoying and especially the last one I would never put in any of my code.
I make only big comments when I need to really draw attention to something special.

They really are a matter of personal preference, but none is really bad unless the code is so super simple.
For example I read and write dozens of DB calls a day, I'm not going to comment each one, I know what a DB call is, and anyone reading it here should or well they will have more problems than reading my code. However when I write some regex I do try to mention what I was looking for because most people can't read regexs

 

[Kolliper]

i only comment on my code if it i need to.
i mean we all know within c++ what this does int main(){ } don't we?
so i am not going to comment on that.
but if we have to use a lot of codes which sometimes is hard to understand its easier to write some comments around the codes to find it back easy.

also if you have really huge files its maybe easier to use comments for search function(if you make it like this //function 512, because if you call this function a lot of times within your program and you have to search through it with the ctrl+f for example function it could take some time)

 

[King Izu]

Some people like to comment every single statement, but in my opinion that's just complete overkill. I comment my methods, types, and properties, which is why I usually don't comment any statements. After all, the statement would probably be a method call or assignment in which case the method or property comment is sufficient (although I don't tend to comment fields in C#, since the name is usually self explanatory). I would only comment a statement if it could be potentially hard to understand for someone else. Example:

lock (packet.Sender.Lock) ((PacketHandler)((object[])info)[1])(packet);

Things like writing a comment for a method call to a method which already has a comment is just pointless in my opinion (especially when In my case I may end up writing a whole paragraph on a method). As for big comments (with little actual words), are just a waste of space and completely unnecessary.

 

[fook3d]

I neither comment in personal scripts nor client scripts.

No reason for me to comment my own scripts because I know what I am writing and fully understand what I am doing.

That said, I know what each part is doing by the query variable, like so:

$pull_user_reg_date = mysql_query("SELECT `row` FROM `table` WHERE `this` = $that");
$user = mysql_fetch_object($pull_user_reg_date);

So I can see what the whole script does that way.

For client scripts, they have no interest in learning, they would rather pay me, so again, will only be me viewing the scripts generally, so the same as above applies here too

 

[Airon]

I always comment my code. I don't comment excessively because it gets on my nerves if there are too many comments like you guys have basically all said. I comment at the beginning of each script to give a brief description of what it's about. Then I comment here and there when needed.

 

[Jordan]

i only comment when i have nothing better to be doing or i know me / someone else will need to read it and wont clearly understand it i normaly comment using //blahhh

or
/*
*=========================
*some random info here
*blahh balhhh balhhhh
*=========================
*/

 

[Aurora]

i sometimes comment my code (if its not only for me)

/// <summary>
/// This window does this
/// </summary>
/// <param name="sender">sender object</param>
/// <param name="e">event argument</param>
public void doSomething(object sender, EventArgs e)
{
....
}

but then again, thats easy, all you do in vs c# is type 3x "/" and it does it more or less automatic

 

[FragFrog]

Now please notice that those methods are just 3-4 lines, now imagine methods wich would contain like 300-400 lines, ain't it easier to see on the begning what it returns ? and what params it eats ? and they are for ? Than searching thru those 300-400 lines

If I ever catch anyone in my coding team writing methods 300-400 lines long they will be looking for a new job in a week, I guarrantee you that.

That being said, I do fully agree with your commenting style - and in fact I've made it mandatory for all projects I work on business wise to use that style.

It's no use saying what a line does, but explaining what a method / class / etc does, why, and what it expects will not only save you a lot of time in the long run, it will also make you rethink your code and see obvious flaws. I wrote quite a bit more on that in this article :smile:

Daevius: once you get a real job you'll see the use of sourcecode documenting engines that will, automatically, parse your code, read trough the comments and put them in searchable pages. The code with stripped comments can also be made available. But the prerequisite for this is that you actually use a uniform method of commenting in the first place, where javadoc is by far the most used.

//edit
A good tool for this is doxygen - I'd show some examples from projects I've worked on but I'm unfortunately not allowed to do so, NDA's and such.

 

[john_d]

comments are good if u plan on distributing your codes.

but i also advice it for personal use also. cause every once in a while coders tend change the way they do stuff. and once u get a few years into coding ull eventually realized that what you coded 2-4 years ago was really silly and needed to be remade. commenting on those funcs would really help in updating stuff

 

[bitblaster]

I put little "reminders" when I comment my code. Reminding myself what everything does...

 

[Monsta.]

When I do VB6, I always comment my stuff so when I look back in the future, I will think "wtf?" but then I look at comments XD

 

[Madison]

Ok I found some of my code at work yesterday that I wanted to share with you.

First of all this is a small tidbit of a script I wrote in Perl.
Second I love Perl, and I've always been pretty darn good at it despite its crazy possibilities of obfuscation. ^^

I've read lots of other peoples comments and some are really funny, you don't always have to be totally serious. I know anytime I read some old code with a nice witty comment I always appreciate it, but that doesn't mean they aren't useful.

 foreach $line (@filelines){

        @splitline = split(/:/, $line);
        $whoibe = $splitline[0];

        if ($flinghash{$whoibe} == 1){
            #then it is already in the hash foo
        }
        else{
            #fling that puppy into the hash
            $flinghash{$whoibe} = 1;

            #bam add that spice
            print FILE3 "$line";

        }

Honestly myself and my Sys admin can read and understand this perfectly, of course it is extremely simple and if it was more complex I would use much better comments. So while I don't recommend this at your job, I thought someone might find it amusing. I personally was laughing hysterically when I wrote it and when I read it.

 

[danse]

Then i will also share with you some code from my word, it's a function wrote by the guy who worked on my place before me, well as you see there is not a single letter as a comment, also all other code looks similar and the only coments are like

<?php

class fooClass
{
	function fooClass()
	{
		// this is a constructor
	}
?>

And that's all for the 400 lines long class,

And now the promised code.

	function get_condition($jaki, $typ)
	{
			
			
			if($jaki==1 && $typ=='firma'){
			if(isset($this->keys[$jaki][11]) && (($this->today<=$this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1))&&$this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,2,2);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,315,315);} else{ return array_push($this->abonament,2,2);}
			}
			
			if($jaki==2 && $typ=='firma'){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,4,4);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,316,316);}
			 else{array_push($this->abonament,4,4);}
			}

			if($jaki==3 && $typ=='firma'){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,6,6);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,317,317);}
			 else{array_push($this->abonament,6,6);}
			}

			if($jaki==4 && $typ=='firma'){
			if( isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,8,8);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,318,318);}
			 else{array_push($this->abonament,8,8);}
			}

			if($jaki==5 && $typ=='firma'){
			if( isset($this->keys[$jaki][11]) &&  ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,14);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,320);}
			 else{array_push($this->abonament,14);}
			}
			if($jaki==6 && $typ=='firma'){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="EF"){array_push($this->abonament,12,12);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="EF"){array_push($this->abonament,319,319);}
			 else{array_push($this->abonament,12,12);
			}}
			
			if($typ=='stowarzyszenie'){
			if($jaki==1){
			if(isset($this->keys[$jaki][11]) && (($this->today<=$this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1))&&$this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,2);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,321);} else{ return array_push($this->abonament,2);}
			}
			
			if($jaki==2){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,46);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,322);}
			 else{array_push($this->abonament,46);}
			}

			if($jaki==3){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,6);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,323);}
			 else{array_push($this->abonament,6);}
			}

			if($jaki==4){
			if( isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,8);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,324);}
			 else{array_push($this->abonament,8);}
			}

			if($jaki==5){
			if( isset($this->keys[$jaki][11]) &&  ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,14);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,326);}
			 else{array_push($this->abonament,14);}
			}
			if($jaki==6 ){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="EF"){array_push($this->abonament,12);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="EF"){array_push($this->abonament,325);}
			 else{array_push($this->abonament,12);
			}}
			}



			if($typ=='biuro'){
			if($jaki==1){
			if(isset($this->keys[$jaki][11]) && (($this->today<=$this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1))&&$this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,33);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="MK" ){return array_push($this->abonament,327);} else{ return array_push($this->abonament,33);}
			}
			
			if($jaki==2){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,35);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="FK"){array_push($this->abonament,328);}
			 else{array_push($this->abonament,35);}
			}

			if($jaki==3){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,6);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="CR"){array_push($this->abonament,317);}
			 else{array_push($this->abonament,6);}
			}

			if($jaki==4){
			if( isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,37);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="ST"){array_push($this->abonament,329);}
			 else{array_push($this->abonament,37);}
			}

			if($jaki==5){
			if( isset($this->keys[$jaki][11]) &&  ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,14);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="LS"){array_push($this->abonament,320);}
			 else{array_push($this->abonament,14);}
			}
			if($jaki==6 ){
			if(isset($this->keys[$jaki][11]) && ($this->today<=$this->keys[$jaki][11] && $this->keys[$jaki][3]==1)&&$this->keys[$jaki][2]=="EF"){array_push($this->abonament,12);}
			 elseif(isset($this->keys[$jaki][11]) && ($this->keys[$jaki][3]==1) && $this->keys[$jaki][2]=="EF"){array_push($this->abonament,319);}
			 else{array_push($this->abonament,12);
			}}
			}
			if($typ=='part_handl'){
			}
	}

 

[Daevius]

I love your spaghetti code Danse