Helpful Information
 
 
Category: Coding tips & tutorials threads
Comment your code

While writing code, always include 'comments'.
Comments are small pieces of code that describe how something works or what it does.
While debugging, comments tell you what the code means so you know how to fix it.
Comments are ignored by the browser/interpreter.
Below are some different types of comments (in no particular order):

<!-- this is a comment in HTML -->

<!-- this is a multi-
line comment in HTML -->


<xsl:comment>this is a comment in XSLT</xsl:comment>

<xsl:comment>this is a multi-
line comment in XSLT</xsl:comment>


// This is a comment in JavaScript

/* This is a multi-
line comment in JavaScript */


/* This is a comment in CSS */

/* This is a multi-
line comment in CSS


// This is a comment in PHP

# This is another type of comment in PHP.
# It'll save you exactly one byte.
# This type of comment was submitted by djr33.

/* This is a multi-
line comment in PHP */


<!-- This is a comment in XML -->

<!-- This is a multi-
line comment in XML -->


<!-- This is a comment in WML -->

<!-- This is a multi-
line comment in WML -->


<!-- This is a comment in RSS -->

<!-- This is a multi-
line comment in RSS -->


<!-- This is a comment in ASP -->

<!-- This is a multi-
line comment in ASP -->


<!-- This is a comment in ASP.NET -->

<!-- This is a multi-
line comment in ASP.NET -->


/* This is a comment in ActionScript */

/* This is a multi-
line comment in ActionScript */


/* This is a comment in C */

/* This is a multi-
line comment in C */


// This is a comment in C++

/* This is a multi-
line comment in C++ */


/// This is a comment in C#

///This is a multi-
/// line comment in C#

If anyone would like to add (or correct) any more types of comments, please reply! :)

Readable code is worth a hundred comments.
function square(n) {
return n * n;
}is better than
// Function to square a number.
eval(function(p,a,c,k,e,r){e=String;if(!''.replace(/^/,String)){while(c--)r[c]=k[c]||c;k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('2 1(0){3 0*0}',4,4,'n|square|function|return'.split('|'),0,{}))

i just gotta laugh at the second example! LOL

Readable code is worth a hundred comments.
function square(n) {
return n * n;
}is better than
// Function to square a number.
eval(function(p,a,c,k,e,r){e=String;if(!''.replace(/^/,String)){while(c--)r[c]=k[c]||c;k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('2 1(0){3 0*0}',4,4,'n|square|function|return'.split('|'),0,{}))
True, but sometimes that's unavoidable. (Like in onClick attributes. I have trouble with functions. :))
I didn't point out that multi-line comments (which are 'closed') allow you to do this:

/*This is a comment */ this(is,some,code);

i just gotta laugh at the second example! LOL
Are you referring to:


<!-- this is a multi-
line comment in HTML -->


<xsl:comment>this is a comment in XSLT</xsl:comment>


<xsl:comment>this is a multi-
line comment in XSLT</xsl:comment>


// Function to square a number.
eval(function(p,a,c,k,e,r){e=String;if(!''.replace(/^/,String)){while(c--)r[c]=k[c]||c;k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('2 1(0){3 0*0}',4,4,'n|square|function|return'.split('|'),0,{}))

I'm assuming

// Function to square a number.
eval(function(p,a,c,k,e,r){e=String;if(!''.replace(/^/,String)){while(c--)r[c]=k[c]||c;k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}('2 1(0){3 0*0}',4,4,'n|square|function|return'.split('|'),0,{})).
LOL, I would go with:

function square(x) {
var squared = 8*8;
return squared;
}
document.write('Square the number: <input name="textfield" type="text" id="textfield" size="5" onClick="square(document.getElementById('textfield').value);">');

LOL, I wrote


dogument.getElemen...

I think the idea of "multi line" comments is a bit misleading.

Comments are marked by some sort of symbol.

There are, as far as I know, only two ways to do this:
1. Use some sort of notation at the start (or middle of the line), then the entire rest of that line is completely ignored as a comment.
2. Have both start and end markers and only the characters within both will be ignored, and in this case it can also stretch beyond a single line.

In PHP, it works like this, and I think that most other languages are similar, at least if they have both types of comment; if not, then only the type they have will apply.

//this is a simple php comment. The whole line is ignored. echo 'This is not shown.'

echo 'This is some text'; //look, this comment says that the text was output
echo 'More'; //and it only makes the end a comment

/* This is another kind of comment */

/* but in this you need both the start and end marker
or it will keep going
and going
and going
and if you don't close it,
it will give you an error when processing your script at the end
End it here: */

/*and here is an example of a comment before code:*/ echo 'This still shows up!';

echo /*within code!*/ 'This shows up too.';

//here's a good trick to know, if you want to debug and not erase your code:
$num = (1+/*2+*/3); //( = 4, ≠ 6 )

/*Also, as you can see, you can't embed one comment in another.
/*That would be weird.*/ Because this is shown! */

//(But remember, if something is already a comment, more // or /* won't change anything.)
//And */ doesn't close a single line comment.

#And this is the last type of comment in PHP. It does one line.

Still a valid article, however. I think it would be useful to in-experienced coders.

Thanks for the suggestions.
I've added:


# This is another type of comment in PHP.
# It'll save you exactly one byte.
# This type of comment was submitted by djr33.

the pound sign saves 1 byte over the double forward slash? thats interesting

It's because there's only one character:

a = one byte

aa = two bytes

or...

# = one byte

// = two bytes

1 character = 1 byte

No, there's rarely a reason to do that. If a function contains a lot of complex code that can't be easily understood, there's a handy way to label it: abstract it out into other functions, with descriptive names.

There's one exception, of course, which is when writing embedded documentation for parsing by tools like PHPDoc, JSDoc. JavaDoc, Doxygen, Haddock, &c.

The # comment form in PHP is discouraged by PECL style guides. Refrain from using it.

How about SQL? No one ever seems to comment their queries...

Single line


SELECT * FROM some_table--Comment

Multiline


SELECT *
/* Comment
goes here*/
FROM some_table

I guess it just doesn't seem feasible to most people... I never thought of using comments in SQL queries because I always looked at them as strings (in PHP), so I didn't think you could use a comment. I didn't realize that SQL had its own commenting system.

Me too, and if anything. I'd just comment it out in the php, after the string. It also makes it look untidy, like Twey said in his first post in this topic.

quite informative. :cool:

SQL comments aren't usually used in tiny strings of code like those you probably use embedded in your PHP. They're used for things like big tables stored in separate files, or large stored procedures.

_This is another type of comment in CSS.
_It both saves you one byte over //
_AND is not recognized as a comment by IE.
_Think about how useful that could be!

Would it be very useful if it isn't recognized as a comment in IE? I really didn't know if you were being sarcastic or not... :D

-magicyte

It's useful for IE hacks. Conditional comments are vastly preferable, though.










privacy (GDPR)