Hi David,

I am a bit disturbed that you wrote "grammer" instead of "grammar" in the very tilte of this forum topic ;)

Anyways, yes we do have several non-native English speaking contibutors and a lot of comments in the source code need to be rewritten. The best branch to fork and fix is the develop branch.

Regarding the online manual, the best way to go for a start would be to copy/paste offending blocks into a comment on the same page and pasting it a second time with fixes.

Thanks for your help.

Haha, tous chez!
Although I think you have spotted a bug in the Firefox dictionary plugin which I rely on! The "grammar"s in the body are all spelt correctly!

tilte -> title

p

In a lot of the code comments there are colons at the end e.g.

// ----------------------- ITEM BLOCK END -----------------------

// Display a button to accept the terms OR info text if current user already accepted them:
if( is_logged_in() )
{	// If user is logged in:

	if( $UserSettings->get( 'terms_accepted', $current_User->ID ) )
	{	// If current user already accepted:
		echo $params['terms_info_before'].T_('You already accepted these terms.').$params['terms_info_after'];
	}
	else
	{	// Otherwise display a button to accept:
		$Form = new Form( get_htsrv_url().'accept_terms.php' );

It's not consistent across the code base. Is it used in any documentation generation? It feels a bit like someone's personal style. I've been taking them out on my branch as they seem a bit pointless.

Any thoughts?

Please don't take them out. They are essential. They indicate the comment applies to what comes next and not to what's above.

Comments are very important to developers and designers. It tells them what the developer was thinking, or the process he/she followed, or what may be required, or may happen next, or how to improve, or where improvements are required. It's a roadmap for developers and those who may contribute to the code now or later. Removing them is like sending someone to a strange country, blind, mute and without a map, a guide or a gps.

@achillis I think you have mis-read my message. No one is talking about removing comments!!!! I know how important they are and what they are for!

I am asking about the colons at the end of the comment line.

The generally accepted convention is that:
comments in / .. / format talk about the block below,
comments starting with "//" typically talk about the 1 or ~2 lines below and
comments on the same line as code talk about that line specifically.

Code consistency makes code easier to read and the use of comments is not standard across the project. In my example I show a few lines of code which have colons at the end of the lines. Here is a section of code which does not have colons at the end of the lines:

/**
 * Uninstall b2evolution: Delete DB & Cache files
 */
function uninstall_b2evolution()
{
	global $DB;

	/* REMOVE PAGE CACHE */
	load_class( '_core/model/_pagecache.class.php', 'PageCache' );

	// Remove general page cache
	$PageCache = new PageCache( NULL );
	$PageCache->cache_delete();

	// Skip if T_blogs table is already deleted. Note that db_delete() will not throw any errors on missing tables.
	if( $DB->query( 'SHOW TABLES LIKE "T_blogs"' ) )
	{ // Get all blogs
		$blogs_SQL = new SQL( 'Get all collections' );
		$blogs_SQL->SELECT( 'blog_ID' );

As you can see there are no colons at the end of the lines. Half the code has colons and half the code does not have colons. I haven't read all the code yet so 50/50 is my guess but I feel it is accurate (so far).

So my question is: are the colons necessary at all? If the colons have a meta-purpose (e.g. documentation generation) then there is a reason to keep them in and that is fine, but comment conventions say they are unnecessary.

Code should be consistent. There is no project code convention document so I am asking you.

@davidnewcomb you are correct, I did miss-read your post. My apologies. I see what you mean.

I have found your coding standards document ( http://b2evolution.net/man/coding-standard-guidelines ). The only advice is to use phpDocumentor (@ param, @ see, etc) and to write some comments. It does not specify how comments should be formatted. The comments across the document are laid out differently in most of the blocks. There is no mention of terminating comment lines with a colon.

So my question is: are the colons necessary at all? If the colons have a meta-purpose (e.g. documentation generation) then there is a reason to keep them in and that is fine, but comment conventions say they are unnecessary.

Yes they are. They indicate the comment applies to what comes next. If anything, add the missing ones but no matter what, don't remove the existing ones.

Thanks, that's all I needed.

I have submitted my first set of documentation bug fixes. I've put all the colons back and added extras in missing areas. I branched off develop as advised.
https://github.com/b2evolution/b2evolution/pull/70

I found a spelling mistake in /rsc/js/zxcvbn.js but I don't think this file is controlled by this project. I might be fixed in a newer version.

Slightly off topic I also have a bug fix pull request waiting ( https://github.com/b2evolution/b2evolution/pull/69 ). It comes off master. Should I resubmit it to come off develop?

No worries, everything is in the queue but it is tax seasons over here, so there will be a little delay due to pressing paperwork :p

/plugins/_captcha_qstn.plugin.php v 6.11.2

Line 156

	function PluginSettingsUpdateAction()
	{
		global $DB, $Messages;

		// Store in this array all questions IDs which are inserted or updated on currect action
		$questions_IDs = array( -1 );

Is that 'correct' action or 'current; action? current would you confirm. And without the colon I suppose it refers to the array defined at line 154 rather that the following code. Would it be better not to have a lie space between the tow related lines 152 and 154 but have it after the comment?