Recent Topics

Typos, spelling mistakes, poor English, grammer

Started by on Mar 08, 2018 – Contents updated: Mar 13, 2018

Mar 08, 2018 18:58    

I'm reading a lot of your source code at the moment and it is full of spelling mistakes, some typos and lots of grammar errors.
I read through a screen reader which means that I can hear all the bumps in a way that a normal speed reader might miss. I'm also a native English speaker which helps!
So instead of moaning about it I thought I'd just go around fixing them all as I work through it. I'm practically reading it all anyway! I'm not familiar with your github project layout, so which is the best branch to use?

The website and online documentation suffers from the same problem and I don't mind sorting that out as well but I'm not really sure what access you'll be prepared to give me or how I should report the changes.

Mar 08, 2018 23:22

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.

Mar 09, 2018 00:07

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


Mar 10, 2018 01:32

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'];
	{	// 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?

Mar 10, 2018 06:27

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

Mar 10, 2018 18:26

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.

Mar 10, 2018 19:49

@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;

	load_class( '_core/model/_pagecache.class.php', 'PageCache' );

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

	// 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.

Mar 10, 2018 21:36

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

Mar 11, 2018 04:58

I have found your coding standards document ( ). 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.

Mar 13, 2018 01:20

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.

Mar 13, 2018 17:16

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.

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 ( ). It comes off master. Should I resubmit it to come off develop?

Mar 13, 2018 20:28

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

Form is loading...

powered by b2evolution free blog software – This forum is powered by b2evolution CMS, a complete engine for your website.