Bug Tracker


Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#10614 closed bug (wontfix)

Commenting style

Reported by: anonymous Owned by:
Priority: low Milestone: None
Component: misc Version: 1.7b2
Keywords: Cc:
Blocked by: Blocking:


From 1.7rc1:

on: function( types, selector, data, fn, /*INTERNAL*/ one ) {

This type of commenting goes against the code style guidelines (http://docs.jquery.com/JQuery_Core_Style_Guidelines)

Change History (6)

comment:1 Changed 5 years ago by anonymous

Same goes with

			if ( window.DOMParser ) { // Standard
				tmp = new DOMParser();
				xml = tmp.parseFromString( data , "text/xml" );
			} else { // IE
				xml = new ActiveXObject( "Microsoft.XMLDOM" );
				xml.async = "false";
				xml.loadXML( data );

comment:2 Changed 5 years ago by addyosmani

  • Component changed from unfiled to misc
  • Priority changed from undecided to low
  • Resolution set to wontfix
  • Status changed from new to closed

Although our style guide doesn't explicitly cover comments of this nature, please remember that comment formats may deviate where it's absolutely necessary. Take for example the code you cited, albeit in a simpler form with the other comment format used:

function on(a , b , c //comments){ console.log('hello world'); }

If you paste this into your console, you'll get a syntax error as the comment is being used inline but expects the rest of the line to also be a comment. Contrast this with:

function on(a , b , c /*comments*/){ console.log('hello world'); }

which preserves the comment but doesn't result in any syntax errors because we've implicitly stated where the comment block ends (this is why '' style comments are generally used on either a dedicated line or at the end of a line and the other style of comments can be used anywhere). I hope that clears it up!

Last edited 5 years ago by addyosmani (previous) (diff)

comment:3 Changed 5 years ago by anonymous

That's not my point Addy. I think it should be:

// The third argument c is special
function on(a, b, c) { console.log('hello world'); }

As the style guide says (http://docs.jquery.com/JQuery_Core_Style_Guidelines#Comments)

Single line comments should always be on their own line

comment:4 Changed 5 years ago by timmywil

The /* internal */ comment is used for internal arguments in several places. I think we all prefer that because it's easy-to-read and makes sense. I'd be ok with adding this exception to the styleguide.

comment:5 Changed 5 years ago by rwaldron

+1 timmywil

Please follow the bug reporting guidlines and use jsFiddle when providing test cases and demonstrations instead of pasting the code in the ticket.

Modify Ticket

Change Properties

E-mail address and user name can be saved in the Preferences.

Note: See TracTickets for help on using tickets.