[haku]

I suck at commenting my code. When I do it, which I usually don't, I do it as an afterthought, and I never know how much I actually should write. So I was talking with my buddy this past weekend who is running a programming agency back home in Canada. I asked how he feels about staff not commenting code, and he said he thinks commenting is a waste of time. "It's like writing a book, then writing a play-by-play in the margins".

Now that works for me, because I'm not so great about doing it. But are other bosses ok with not commenting? Do you guys do it? And if you do, do you do it because you like to, or because you are made to?

[herkalees]

I comment all websites that aren't mine (because nobody else will ever work on *my* websites) and I comment them at the end of every major layout </div>, sometimes an 'updated xx/xx/200x' at the top of the file, and all JavaScript/PHP/.Net files practically get documentation at every step in the file (or at least the non-obvious steps).

Commenting is good because someday, somebody else will open that file and scratch their head.

[djeglin]

Agreed. I comment at the beginning and end of all majr layout sections, and in other places where needed. I work a lot with jsp pages, where there is jstl login in place within the file, so often I comment those sections to explainthe logic as well.

All of this is largely because I work frequently in a team on one project, so there is a good chance that someone else may have to do something with my work.

I also like to comment javascript fairly thoroughly for the same reason (and to remind myself of what I was doing in the future!)... It just seems to make sense to me to provide a plain english explanation of what is going on in a script for the uninitiated.

David

[Limbo]

I only comment closing structural elements e.g.

</div> <!-- end content -->

...

</div> <!-- end navigation -->




an I'm totally pedantic about stylesheets - I crack the whip here about well laid out CSS - makes it much easier to edit if it's well presented - especially if it's someone elses work.

That book analogy is terrible. Sack him.

[PoeT4eva41]

I comment commonly in php and js. Html not so. I comment even if it's my project. I like commenting .

PHP Code:

/**
     * Functions.php
     * Last change: 18.11.07
     */
    
    /**
     * Function to get error ids and messages from database
     *
     * @param string $var
     * @param string $return
     * @return string
     */
    
    function getError($var, $return='value')
    {
        $rst = mysql_query("SELECT * FROM `languages_errors` WHERE `var` = '".$var."' AND `language` = '".$GLOBALS['selected_language']."'");
        $row = mysql_fetch_assoc($rst);
        return $row[$return];
    }

    /**
     * 
     * Function to get information about registered users. 
     * $return can be "all". It will return array with all options of user.
     * if $userid is null, then $userid = logged user id :).
     * It also return a user type 0, when $return = type and no user logged
     *
     * @param string $return
     * @param integer $userid
     * @return string
     * 
     */

    function useropt($return, $userid='')
    {
    
        if (!$userid)
        {
            $rst = mysql_query("SELECT `user` FROM `users_sessions` WHERE `session` = '".session_id()."'");
            $row = mysql_fetch_array($rst);
            
            $userid = $row['user'];
        }
        elseif (!is_numeric($userid))
        {
            return false;
        }
    
        $rst = mysql_query("SELECT * FROM `users` WHERE `id` = '".$userid."'");
        $row = mysql_fetch_assoc($rst);
        if (mysql_affected_rows())
        {
            if ($return == 'all')
            {
                return $row;
            }
            else
            {
                return $row[$return];
            }
        }
        else
        {
            if ((!$userid) && ($return == 'type'))
            {
                return 0;
            }
            else
            {
                return false;
            }
        }
        
    }
    
    /**
     * This function returns logged user permissions
     *
     * @param string $permission
     */
    
    function permission($permission)
    {
        
        // Usertype
        $rst = mysql_query("SELECT `type` FROM `users` WHERE `id` = '".useropt('id')."'");
        if (mysql_affected_rows())
        {
            $row = mysql_fetch_assoc($rst);
            $usertype = $row['type'];
        }
        else 
        {
            $usertype = 0;
        }
        
        // Permission
        $rst = mysql_query("SELECT `value` FROM `usertype_permissions` WHERE `usertype` = '".$usertype."' AND `permission` = '".$permission."'");
        
        // If there is an information about this permission, return value, else return 1.
        if (mysql_affected_rows())
        {
            $row = mysql_fetch_assoc($rst);
            return $row['value'];
        }
        else 
        {
            return 1;
        }
        
    } 


That's an example of my code

[pgo]

I don't comment HTML at all. It's so structural that it's pointless. Though Limbo's comments are useful.

Programming, in some cases, I comment the hell out of it in other cases I don't comment at all. If it's something only I'm editing and using, I do only "reminder" comments to myself. However, I've got a small set of JavaScript scripts together for our subsidiary companies that is insanely commented (there's also a production version of each without comments):

	/*
		  Method:	init
		============================================================
		 Summary:	Grabs all links withing #main-content which have
		 		an href set and calls check() for each.  Does 
				not execute if DOM methods are absent.

		  Params:	none
		------------------------------------------------------------
	*/

	init: function() {
		if (!document.getElementsByTagName || !document.getElementById) return false;
		var all = document.getElementById("main-content").getElementsByTagName("a");
		for (i = 0; i < all.length; i++) {
			if (all[i].href) {
				ICxLinks.check(all[i]);
			}
		}
	},

	/*
		  Method:	check
		============================================================
		 Summary:	Splits up the link and pulls the extension from
				the link.  If that extension is found in either
				of the arrays (openInNewWindow and 
				openInSameWindow) it applies the appropriate 
				behavior and appends <span>(s) as necessary.

				* If external links should open in a new window,
				check if this 

		  Params: 	<a> object
		------------------------------------------------------------
	*/

	check: function(link) {
		// get the extension of the link
		var extension = ICxLinks.getExt(link);

		// default values for properties of a link
		var isExternal = false;
		var isNewWindow = false;

		// check if the link is external
		if (link.href.indexOf(ICxLib.thisDomain) == -1) isExternal = true;
		// check if the link doesn't have a child image
		if (link.getElementsByTagName("img").length == 0) isImageLink = false;
		// if external links open in new windows, this link is external, and not an image link, set it to open in a new window
		if (ICxConfig.externalNewWindow && isExternal) isNewWindow = true;

		// loop through the new window extensions array
		for (j = 0; j < ICxConfig.openInNewWindow.length; j++) {
			if (extension == ICxConfig.openInNewWindow[j]) {
				isNewWindow = true;
				// if the link does not contain any images, append a span with class equal to its extension
				if (link.getElementsByTagName("img").length == 0) {
					ICxLinks.appendSpan(link, extension);
				}
			}
		}

		// loop through the same window extensions array
		for (j = 0; j < ICxConfig.openInSameWindow.length; j++) {
			if (extension == ICxConfig.openInSameWindow[j]) {
				// if the link does not contain any images, append a span with class equal to its extension
				if (link.getElementsByTagName("img").length == 0) {
					ICxLinks.appendSpan(link, extension);
				}
			}
		}

		// by now, if we've determined the link should be opened in a new window, do so
		if (isNewWindow) {
			ICxLinks.newWindow(link);
		}
	},

The version with comments: 11KB. The version without: 5KB. It would be even smaller if I had used PACKER, but it caused some cryptic error, so I said forget it.

[adras]

Commenting HTML can sometime cause IE bugs. Especially when you are all about clean XHTML/CSS.

As for server side coding, my boss at the day job doesn't care, so I comment only when necessary.

[Herr Kurm]

this programming thing is such a load of cock.

[Limbo]

CSS Sample - commented throughout.

*
	---------------------------------------------
	Copyright ** 2008
	---------------------------------------------
	Colour Palette 
	
	LOCAL
	.	Bedroom - Orange: #f7a529
	.	Bathroom - Blue: #00adde 
	.	Kitchen & Dining - Red: #ef3929
	.	Living Room - Purple: #b13680
	.	Garden - Green: #82bd43
	
	SYSTEM
	.	Pale Blue: #f5fbfd 
	---------------------------------------------
	*/
	
	
/* generic HTML */

	html {margin:0;border:0;padding:0;background:#fff;color:#333;}
	body {margin:0;border-top:4px solid #000;padding:0;font-family:georgia, serif;font-size:100%;text-align:center;background:#fff;}
	
	h1 {position:absolute;top:-1px;left:-1px;height:1px;width:1px;font-size:0.01em;z-index:-1;}
	h2 {margin:0 0 8px 0;border:0;padding:0;font-size:1.4em;font-weight:normal;height:30px;background:#fff;border-bottom:1px solid #ccc;}
	h3 {margin:0;border:0;padding:8px 0;font-size:0.7em;color:#000;text-transform:uppercase;letter-spacing:2px;border-bottom:1px solid #eee;}
	h4 {margin:0;border:0;padding:8px 0;font-size:0.6em;color:#777;text-transform:uppercase;letter-spacing:2px;}
	p {margin:0;border:0;padding:8px 0;line-height:1.6em;font-size:0.7em;}
	
	ul {margin:0;padding:0;}
	li {margin:0;padding:0;font-size:0.7em;line-height:1.6em;}
	
	a {margin:0;border:0;padding:0;color:#000;}
	a:link, a:visited {margin:0;border:0;padding:0;text-decoration:none;color:#000;}
	a:hover, a:active {margin:0;border:0;padding:0;text-decoration:none;color:#777;}
	a:focus {outline:none;}
	
	address {margin:20px 0;border:0;padding:0;font-size:0.7em;font-style:normal;line-height:1.5em;}
	blockquote {margin:0;border:0;padding:0;background:#f5fbfd;}
	
	table {margin:0;border:0;padding:0;}
	tr {margin:0;border:0;padding:0;}
	td {margin:0;border:0;padding:0;}
	
	iframe {margin:20px 0;border:0;padding:0;}
	
/* header */

	#access {margin:0;border:0;padding:0;position:absolute;top:-100px;left:-100px;height:1px;width:1px;font-size:0.01em;z-index:-2;} 
	
	#headband {margin:0;border:0;padding:0;background:url(../images/system/colour-bar.gif) repeat-x #fff;height:150px;}
	#header {margin:0 auto;border:0;padding:0;width:940px;height:99px;text-align:left;}
	
	#logo {margin:0;border:0;padding:40px 0 0 0;float:left;}
	#logo a {margin:0;border:0;padding:0;background: url(../images/system/chic-logo.gif) no-repeat #eee;width:200px;height:59px;float:left;}
	
	#searchbar {margin:49px 0 8px 0;border:0;padding:0;float:right;background:#fff;width:500px;text-align:right;}
	#searchbar fieldset {margin:0;border:0;padding:0;}
	#searchbar input {margin-left:5px;padding:1px;font-size:0.7em;font-family:verdana, serif;}
	
	#headernav {width:650px;text-align:right;float:right;background:#fff;}
	#headernav li {display:inline;padding-left:13px;font-family:georgia, sans-serif;font-size:0.9em;}
	
	#headernav a {color:#000;}
	#headernav a:link, #headernav a:visited {color:#000;}
	#headernav a:hover, #headernav a:active {color:#777;}
	
/* layout */

	#foundations {margin:0 auto;border:0;padding:0;background:#fff;text-align:left;width:940px;}
	
	#left-column {width:222px;background:#fff;float:left;}
	#left-column adresss {margin:20px 0;}
	#left-column h2 {width:200px;}
	
	#content {width:496px;padding:0 0 30px 0;background:#fff;float:left;}
	#right-column {width:204px;padding:0 0 30px 0;background:#fff;float:right;}
	
/* content generic */

	#content ul {margin:10px;padding:0;background:#fff;}
	#content li {margin:5px;padding:0;background:#fff;list-style-type:square;}
	#content a {font-weight:bold;}
	#content a:link, #content a:visited {text-decoration:none;}
	#content a:hover, #content a:active {text-decoration:underline;}
	
	#content p.info {margin:0 0 30px 0;padding-left:20px;border-bottom:1px solid #000;background:url(../images/system/grey-point.gif) no-repeat;} 
	#content p.button {border:0;border-bottom:1px #000 solid;margin-bottom:20px;}
	#content p.button img, #content p.button img {background:none;border:0;}
	

/* house sections */	
	
	/* bedroom */
	#bedroom #content h2, #bedroom #content h3 {color:#f7a529;}
	
	/* bathroom */
	#bathroom #content h2 {color:#00adde;}
	
	/* kitchen & dining */
	#kitchen #content h2 {color:#ef3929;}
	
	/* living room */
	#product-nav li.living a:link, #product-nav li.living a:visited 
	
	/* garden */
	#product-nav li.garden a:link, #product-nav li.garden a:visited {}
	
/* homepage */

	#home #content .intro {margin:20px 0;padding:0;color:#eee; solid}

/* search */
		
	#search #content #adv-search p {margin:0;border:0;padding:0;}
	
/* site map */

	#content .site-map ul {margin:0;padding:0 0 0 25px;}
	#content .site-map li {font-size:0.7em;}
	#content .site-map li ul li {font-size:1em;}
	
/* footer */

	#footer {}
	#footer ul {}
	#footer li {}
	
	#footer a {color:#000;}
	#footer a:link, #footer a:visited {color:#000;}
	#footer a:hover, #footer a:active {color:#777;}
	

	
/* fin */

Examplified.

[2Dfruit]

I remember having a divilicious layout once and commenting on it because there were so many of them. caused some weird side effects ( i opted for overuse of whitespace). I never comment on code, css html or php. I don't work with a team so nobodys ever going to use my code apart from me.............and if they try....God help them!!

mwhahahahahaha

[iblastoff]

basically, if you do very simple stuff, then its probably not needed.

very silly to say comments aren't needed though. i generally do the same as limbo and comment which div closes which div so i can 'see' the layout better. for php i definitely comment what certain functions do.

[brooks]

I don't code but when I'm writing mark-up like HTML or CSS I only comment on bigger projects and I have loads of elements flying all over I might consider commenting the CSS.

If I coded with PHP etc. I think I'd have to because it's totally lost on me right now.

[3n1gm4]

I tend to try to use "self commenting code" or [link=http://en.wikipedia.org/wiki/Hungarian_notation]hungarian notation[/link] whenever possible, this cuts down on commenting but adds to the readability of the code... i also try to not use cryptic variable names such as $a or whatever. and whenever i do some complicated logic, i try to explain it in a comment for either myself in the future or a possible colleague that may be working with the file

[haku]

That book analogy is terrible. Sack him.

He's the boss!
I think the problem (not for him though) is that the guy is pretty much a genius when it comes to code, and he can read through code and see whats going on without the comments, so he doesn't see the worth in them.

For everyone who comments, do your bosses require it as well?

[3n1gm4]

Originally Posted by haku

"It's like writing a book, then writing a play-by-play in the margins".

more like writing a book and then writing the cliff notes for it... what would you rather do, read the book, or the cliff notes?

[freelancr]

I don't comment XHTML or CSS (well, apart from to add my contact details) but I do try to comment as much of the server side programming that I can (PHP/ASP.NET).

9 times out of 10 it will just be me working on something on my own, but in the past I have worked on something, then someone else is asked to do some work on it afterwards, and I have been contacted by them.

Though commenting is good, writing neat and clear code is better. It would be worse to comment a load of messy shit than to not comment something that is easily followed. Most books I have read try to get this message across.

This is a good guide:
phpBB3 &bull; Coding Guidelines

[Limbo]

Originally Posted by haku

he can read through code and see whats going on without the comments

Most coders can do that on projects THEY have developed - but for team environments commenting is useful - especially when maintenance might be carried out on a site developed by another.

That, said Good code will always be be good code. regardless of comments.

Simply spacing elements within the page can work equally well.

Tab - double tab - double return - treble return etc...

[emil]

I only comment bits in the css that I feel might pose problems. I did use extensive comments on a couple of large projects, but it's extremely time consuming. I am also working on poorly written code with no comments. That is indeed a nightmare.

Nice avatar Limbo.

[dtrenz]

even if it's your code, maintaining or updating a project you haven't had to touch in a long while can be made much easier with comments.

i'm talking about actual code, not mark-up.

how many of you have looked at code you wrote 6+ months ago and said "what the hell was i trying to do here?!"

i have. especially since my coding style, structure, flow, and methodology is constantly evolving. I often don't even recognize code that is more than a year old.

so comments are good if you work solo, and essential if you work collaboratively.

[misterphotoshop]

Its very rare when I comment in HTML although sometimes I do in my stylesheets just to clear some things up. It all depends on how well planned the website is I guess.