Problem/Motivation

We have a de facto standard that module and theme names should be capitalized using "Sentence case for their names", rather than "Proper Name Case" (see http://drupal.org/node/542202). However, grammatically in English, module names are "names of specific things", and therefore are grammatically proper names.

Our standard for naming *pages and headers* in Drupal is to use sentence case, and it appears that this standard has been mis-applied to the names of modules and themes.

Proposed resolution

Change the standard so that Proper Name Case should be used for module names, or just don't have a standard (because it would be a pain to go back and change all the thousands of core/contrib modules that are incorrectly using Sentence case now).

Remaining tasks

Decide on the standard. Update the "Writing .info files" page (http://drupal.org/node/542202) with this standard (including example code at the top, which could use a more interesting module name as well). If we decide that we want to enforce proper name case, start by doing this with the Drupal 8 core modules.

There is also a related Coder module issue on this:
#1103208: Projects' names should be checked in .info files for correct capitalization.

User interface changes

Module names may need to change.

API changes

None.

Suggested changes

This is #33 below with a few edits:

a) On http://drupal.org/node/542202 (Writing .info files):
- We change the code at the top to use the sample name

name = Really Neat Widget
description = Provides a really neat widget for your site's sidebar.

- Farther down on the page, we change the text of the explanation of the "name" line to say:

The displayed name of your module. Since module names are proper names, it should be capitalized as a proper name (e.g., "Really Neat Widget", not "really neat widget" or "Really neat widget"), and it should be a human-readable name (not really_neat_widget). This name will appear on the Modules page.

b) We include some notes on http://drupal.org/node/604342 (Interface text) about when to use Sentence case and when to use Proper Noun Case:

Capitalization

Page titles in headings in Drupal should generally use "sentence case" where only the first word is capitalized, except for proper nouns and other words which are generally capitalized by a more specific rule. Examples: "Block administration", "Menu list", "Install new theme".

When referring to the name of a module or theme directly, such as in documentation, use "proper name" case, since module and theme names are proper names in English. For example, use "How to configure private forums with the Taxonomy Access Control module" instead of "How to configure private forums with the Taxonomy access control module". The latter is ambiguous as it could be interpreted that you have a module called "Taxonomy" that is an example of an access control module or that we are using an un-named module providing access control for Taxonomy.

c) We update the guidelines on how to write help pages (hook_help()) to model this standard -- right now the standard is about the Node module, so we should pick a different example that has a multi-word module name -- http://drupal.org/node/632280

Comments

Michelle’s picture

jhodgdon on IRC pointed me at http://drupal.org/style-guide/content#moduleref which would need to be changed as well.

Michelle

jhodgdon’s picture

This was possibly based on:
http://drupal.org/style-guide/content#headings
where we adopted sentence case for everything... and we also adopted sentence case for core modules when we did:
http://drupal.org/node/632280
(although it is not mentioned there, you can see this in all the hook_help() and .info files in core, which were standardized for d7) -- the standards were adopted/discussed on this issue: http://drupal.org/node/537828

Michelle’s picture

http://drupal.org/style-guide/content#headings gives the answer right there:

Everything else except proper names is in lower case. (Drupal is a proper name.)

Project names (like Drupal) are proper names. Therefore they are exempt from having parts of them forced to lowercase.

Michelle

Kristen Pol’s picture

I've also also thought it was weird to have module names with "sentence casing" rather than "proper name casing". I didn't even know this was a "rule" before I created my modules so mine are:

Featured Content
SEO Friend
Views Examples

which seems right to me!

Btw, when I asked for a CVS account when submitting my Featured Content module, no one complained about the casing of the project name.

Kristen

richardp’s picture

I'd just like to add my voice in support of Michelle here. This was pointed out to me here: #1423798: Do not capitalize first letters in Arrange fields project's name., and it just doesn't seem right, since my module (Arrange Fields) is a proper name.

This sentence would just look bizarre to me:
"After downloading Arrange fields you should visit your admin section."

It's confusing. It makes it look like the name of the module is "Arrange."
Another example I thought of was the module Backup and Migrate. This sentence just creates confusion:
"After you download Backup and migrate to your site, you should visit..."
See what I mean? The phrase "and migrate" appears to be an instruction to the reader, and not part of the module's name. I think it would just confuse users.

Richard

joachim’s picture

That's an excellent point, and one I agree with.

I just can't help finding it shouty in menus, the modules admin page, and d.org project pages :/

Michelle’s picture

"Shouty" would be VIEWS BULK OPERATIONS. ;)

Maybe you find it shouty because you don't even capitalize your name? :)

I don't find "Michelle Cox" to be shouty...

Michelle

joachim’s picture

It's a UK / US difference. Newspaper headlines aren't capitalized here:

Guardian: Al-Qaida-inspired plotters planned London attack
New York Times: Romney, Eye Still on G.O.P. Rivals, Turns Back to Obama

jcisio’s picture

I'm in support for Michelle, too. We always captitalize proper nouns.

@joachim: the capitalization of headline/title is another story.

jcisio’s picture

I've just taken a look at the list of top modules. There is no rule about projet name. It is written as-is. Examples: "Content Construction Kit (CCK)", "Google Analytics", "Backup and Migrate", "jQuery UI", "Global Redirect", "CKEditor - WYSIWYG HTML editor" vs "Chaos tool suite (ctools)", "Administration menu", "Advanced help"...

Dave Reid’s picture

I'm firmly in the camp of "Use sentence case if you can, otherwise name it whatever the heck you want." The only restriction that should actually count is you have to use lowercase for the actual module file names since we can't have a mymodule.module and MyModule.module both exist since they'd conflict.

Michelle’s picture

I bet even the UK headlines don't write, "The United states invades Saudi arabia" though. We're not talking about capitalizing whole sentences; we're talking about proper names.

Michelle

Michelle’s picture

Cross posted with Dave... I'm totally fine with lower case in code. That's a coding standard then and that's fine.

Michelle

klonos’s picture

I'm the one who filed #1103208: Projects' names should be checked in .info files for correct capitalization. (so I guess I'm also the one to blame for all the fuss there as well as perhaps here too).

I just need to stress that I didn't file that issue against core or d.o webmasters but against Coder (as a feature request) since that module's goal is to ensure coding standards/practices that are already in place in Drupal coding (and d.o in general) are actually being followed/enforced. That issue over there is not the place to debate over whether that coding standard should be in place to begin with or not. Hence this issue here.

I's also like to say that I'm in favor of allowing the developers to name their "babies" however they please. ...,but only if this is defined as an official coding standard/practice in Drupal and d.o.

Now that I've made these clear, I'd like to be the "devil's advocate" here...

@jcisio: Hai-Nam, #10:

Some of these are allowed because there are exclusions to the rule. For example when the name includes acronyms or 3rd party products with "exotic" capitalization.

"Content Construction Kit (CCK)": should perhaps better be "Content construction kit (CCK)", but I guess it's also fine as is because the project's machine name is cck and these letters are acronyms.
"Google Analytics": this is a 3rd party name and that's how Google spells it.
"Backup and Migrate": should be "Backup and migrate"
"jQuery UI": again 3rd party and that's exactly how it's spelled by the authors. So it's fine. (even if it http://jqueryui.com/ didn't exist, still "jQuery" is spelled like so and "UI" is an acronym)
"Global Redirect": should be "Global redirect"
"CKEditor - WYSIWYG HTML editor": just fine since "CKEditor" is the libraries official spelling, "WYSIWYG" & "HTML" are acronyms.

As for "Administration menu": it used to be "Administration Menu" before #272920: Complete text strings overhaul

klonos’s picture

...on another note, projects here in d.o (especially the most popular ones) are vaguely considered "products" of "3rd parties" (their maintainers or original authors). So, I think that in cases where a module extends the functionality of another project and that project's name was mentioned in their name, then in such cases capitalization should be allowed. Let me give an example of what I mean:

We have "Views", so "Views Slideshow" should be "Views slideshow" according to Drupal coding/naming standards. If the module was to be called "Slideshow of Views" it should be fine, since "Views" is a proper name of a module ("3rd party product"). According to Drupal standards though, it would have to be named "Slideshow of views". I don't like that either :/

...so I guess this discussing here does have a reason.

Michelle’s picture

You point out how these 3rd party products spell their names the way they want and say that's fine and yet it's not fine if Drupal project owners want to spell their product names a certain way? Seems like a double standard to me and also is getting into that dangerous territory of pushing the concept of community owned code too far and treating the people who put their heart and soul into creating something like their desires for the project are unimportant.

I am perfectly fine with Coder enforcing capitalization in code. That makes sense. Even Google Analytics would be google_analytics in code. What I'm not fine with is dictating the casing of the proper name of projects elsewhere, especially when the standard goes against the rules of English for proper names.

Michelle

klonos’s picture

What I'm trying to say is that I too want this issue here to be accepted (the first part, the "let project authors control their own project names" I mean) so that project's can be freely named as their creators wish. I was trying to explain that for as long as the standard stands as is, the other issue makes sense and that the standard should be respected. Hope I make myself clear.

Michelle’s picture

I was trying to explain that for as long as the standard stands as is, the other issue makes sense and that the standard should be respected.

As I said in #3, the current standard is to capitalize proper names. Therefore, under the current standard, Artesian Forum would be correct. So please respect the current standard and stop telling people to change their correctly capitalized proper names.

Michelle

klonos’s picture

Proper names huh? Under which project is this filed under? Right! ...Drupal Core. And I own a Toyota Car and live in London City, which is in the UK Country, which in turn is in the European Continent of the Earth Planet. All these make as much sense to me as Artesian Forum does.

If you take a look at the core modules and exclude the ones that use single-word names, you'll see:

Content translation
Contextual links
Database logging
Field SQL storage
Field UI
OpenID
PHP filter
RDF
Update manager

...where "SQL", "UI", "PHP" and "RDF" were allowed because they are acronyms and "OpenID" excluded because it's 3rd party (even its vendor's site says "OpenID Foundation website" - not "OpenID Foundation Website").

IMHO you insist on playing the "proper names" card, when in fact you are confusing "names" with "nouns". That said, I'll shut up from now on and patiently wait for a final decision/answer on this matter from the people that make the rules we are supposed to follow here in d.o

jhodgdon’s picture

Let's keep this civil, OK?

So... Can I just step in and say a few things here?

a) We definitely currently have a standard for Drupal Core (or Drupal core if you prefer) to do *everything* in Sentence case (or all lower case in some cases, such as "edit" links on the content management overview page).

b) In general, we encourage contributed modules to follow the same standards as Drupal core.

c) Module names are definitely proper names in a grammatical sense -- they are the names of particular things (check dictionary.com or your favorite dictionary for what "proper names" means). And if they weren't proper names, why would we capitalize the first letter at all?

d) I believe that the current standard for using Sentence case for proper nouns is just wrong. We have adopted a standard for using Sentence case for headings and page titles, but I don't think it's ever correct to use Sentence case for proper nouns.

Therefore, I think we should change this standard, unless someone can come up with a respected style manual somewhere that advocates using Sentence case instead of Title Case for capitalization of English-language proper nouns.

Michelle’s picture

@jhodgdon: Thanks. :)

@klonos: This is a do-ocracy, not a dictatorship. The standards are formed by discussing and attempting to come to a community consensus. Also, I know the difference between a proper name and a noun. In the case of this project name, the proper name is "Drupal" and the "core" is likely added to make it clear that the project refers to the core of Drupal and not contrib, etc. That said, I wouldn't have a problem if they wanted to use Drupal Core but I don't think it's a good example. "Artesian Forum", however, is a proper name consisting of two words. It is not the "forum" component of Artesian. It is, simply, "Artesian Forum". That is its name.

Michelle

klonos’s picture

I know I said I'd shut up, but...

I thought that it was another forum project called "Artesian" (IOW that the "forum" was there to describe the module's functionality/purpose/type).

I guess we can keep going on forever with this and it'd still be like people from different countries trying to convince each other that they are driving on the "wrong" side of the road :/

Michelle’s picture

I have, actually, been contemplating naming it simply "Artesian" when it's released but that is because it is going to be more than a forum and I'm not sure the name will end up being accurate. At this time, though, the project's official, proper name is "Artesian Forum". And I have no intention of renaming "Advanced Forum" to simply "Advanced" as that would be silly. Again, "Forum" is part of the name. So, if you prefer, we can use that as the example rather than Artesian Forum.

And, yes, this could keep going on forever if you continue to insist that you know better what something's name is than the person who named it but, frankly, I'm tired of it and would rather spend my time coding than trying to explain the rules of English to you.

I've made it quite clear that I think we should keep the existing standard of capitalizing proper names and that the project authors are to decide what part of the project title constitutes the proper name of the project. Further posts on this would be pointless. Unless someone has some specific question of me or some other reason I need to respond, I'm done.

Michelle

jhodgdon’s picture

Status: Active » Needs review

Going back to the original issue report here... Looking at Writing .info files, the page says

name (Required): The displayed name of your module. It should follow the Drupal capitalization standard: only the first letter of the first word is capitalized ("Example module", not "example module" or "Example Module"). Spaces are allowed as the name is used mainly for the display purposes.

So. I propose that we change this. We don't have a "Drupal capitalization standard" for proper names, and module names *are* grammatically Proper Names in English.

I think this should read:

name (Required): The displayed name of your module. Spaces are allowed as the name is used for display purposes.

In other words, I think we should just take the capitalization out of it entirely. We have a whole bunch of core and contrib modules that have been following this incorrect advice for many years, but that doesn't mean we should propagate it. And I don't think we can just decide now that all of them are doing the wrong thing either.

This is now a proposal for a new standard. Any comments on this new standard? I will update the issue summary...

jhodgdon’s picture

Title: Either let project authors control their own project names or standardize on correct capitalization » Decide on coding standard for capitalization of module names
Category: feature » task
xjm’s picture

I'm on board with #24.

I personally agree with Michelle that "Taxonomy access control" looks dumb.

Good: "How to do foo with the Taxonomy Access Control module."
Bad: "How to do foo with the Taxonomy access control module." -- sounds like the Taxonomy module is an access control module. Confusing!

jhodgdon’s picture

RE #26 - Definitely!!!! What we've been doing is definitely wrong. I tried to fix it when we adopted the hook_help() standards during the d7 cycle but I came in too late in the process during the ever-lengthening string freeze, and it wasn't fixed then.

jhodgdon’s picture

Even in page titles this case should be respected. For instance if your settings page is called ""Settings for the Taxonomy Access Control module", then that would be the proper way to capitalize it.Not "Settings for the Taxonomy access control module", which like #26 is hard to read (and incorrect).

catch’s picture

#24 sounds good, I think #26 could go into the docs maybe?

Michelle’s picture

#24 sounds perfect to me. Thanks for breaking the stalemate, jhodgdon! :)

I'd mark it RTBC but perhaps that should be left to someone who wasn't involved in the more heated areas of the thread. ;)

Michelle

Michelle’s picture

Issue summary: View changes

Create issue summary

yoroy’s picture

Sounds good. The example in 26 shows how the current guideline can lead to confusion, it might be good to have that example in the docs.

from the example code in [#542202]

name = Example module

should probably be updated to something like

name = My Great Module
Tor Arne Thune’s picture

Status: Needs review » Reviewed & tested by the community

I agree with #24, and also think the examples in #26 should be incorporated into the documentation, to give it weight and make it easier to understand the reasoning behind a rule guideline like that. Seeing as so many agree, RTBC.

jhodgdon’s picture

Status: Reviewed & tested by the community » Needs review

Agreed on #31, except let's not put "module" in the module name.

OK. Here's a slightly more involved proposal:

a) On http://drupal.org/node/542202 (Writing .info files):
- We change the code at the top to use the sample name

name = Really Neat Widget
description = Provides a really neat widget for your site's sidebar.

(other suggestions welcome, but I don't want it to include the word "module" in the module name, as that will confuse the rest of this).

- Farther down on the page, we change the text of the explanation of the "name" line to say:

The displayed name of your module. Since module names are proper names, it should be capitalized as a proper name (e.g., "Really Neat Widget", not "really neat widget" or "Really neat widget"), and it should be a human-readable name (not really_neat_widget). This name will appear on the Modules page.

b) We include some notes on http://drupal.org/node/604342 (Interface text) about when to use Sentence case and when to use Proper Noun Case:

Capitalization

Page titles in headings in Drupal should generally use "sentence case" [link to Wikipedia?]:
Block administration
Menu list
[more or better examples?]

When referring to the name of a module or theme directly (for instance, in a Help page), use "proper name" case, since module and theme names are proper names in English [link to Wikepedia or dictionary.com?]:
Good: "How to do foo with the Taxonomy Access Control module"
Bad: "How to do foo with the Taxonomy access control module"
(The latter is ambiguous -- it could be interpreted that you have a module called "Taxonomy" that is an example of an access control module.)

c) We update the guidelines on how to write help pages (hook_help()) to model this standard -- right now the standard is about the Node module, so we should pick a different example that has a multi-word module name -- http://drupal.org/node/632280

Michelle’s picture

#33 looks great to me. Thanks again for taking this on!

Michelle

xjm’s picture

How about "How to configure private forums with the Taxonomy Access Control module"--that sounds more like a real help document title. ;)

Tor Arne Thune’s picture

Wow, that was fast. Nothing to comment on in #33; looks good to me.

jhodgdon’s picture

Agreed on #35. :)

Kristen Pol’s picture

Status: Needs review » Reviewed & tested by the community

@jhodgdon #33 and #35 looks great to me to me too. Marking RTBC since several people have agreed.

Kristen

webchick’s picture

Title: Decide on coding standard for capitalization of module names » Decide on coding standard for capitalization of module names [policy, no patch]

Clarifying the RTBC here.

jhodgdon’s picture

OK, it looks like we have agreement between webchick, xjm, Michelle, and Kristen Pol on #33/35 being the standard. Tor Arne Thune, yoroy, and catch agreed to #24, which was not quite the same standard.

So I think we should leave this at RTBC for a couple of days and see if there area any further discussions/ideas/objections, and then edit the pages listed in #33 to make this the standard.

jhodgdon’s picture

Issue summary: View changes

note on what needs to be updated if a new standard is adopted

Michelle’s picture

I put #33 combined with #35 and also some suggested changes of my own into the issue summary under "suggested changes".

Michelle

Michelle’s picture

Issue summary: View changes

Added suggested changes to the summary

jhodgdon’s picture

Michelle - what changes specifically? Do we need to put this back to "needs review", since no one has agreed to this new version, or are they just typographical?

Michelle’s picture

Well, this is the original:

Page titles in headings in Drupal should generally use "sentence case" [link to Wikipedia?]:
Block administration
Menu list
[more or better examples?]

When referring to the name of a module or theme directly (for instance, in a Help page), use "proper name" case, since module and theme names are proper names in English [link to Wikepedia or dictionary.com?]:
Good: "How to do foo with the Taxonomy Access Control module"
Bad: "How to do foo with the Taxonomy access control module"
(The latter is ambiguous -- it could be interpreted that you have a module called "Taxonomy" that is an example of an access control module.)

And this is with #35 and also my changes:

Page titles in headings in Drupal should generally use "sentence case" where only the first word is capitalized, except for proper nouns and other words which are generally capitalized by a more specific rule. Examples: "Block administration", "Menu list", "Install new theme".

When referring to the name of a module or theme directly, such as in documentation, use "proper name" case, since module and theme names are proper names in English. For example, use "How to configure private forums with the Taxonomy Access Control module" instead of "How to configure private forums with the Taxonomy access control module". The latter is ambiguous as it could be interpreted that you have a module called "Taxonomy" that is an example of an access control module or that we are using an un-named module providing access control for Taxonomy.

I don't think it's anything that affects the status. Just changed the wording a bit, added examples, changed the notes about linking to wiki to an explanation since the wiki page where it's explained is huge... If you don't like it, I'm not set on the changes. Was just trying to clean it up a bit so it's ready for copy/paste instead of having a bunch of notes in it. :)

Michelle

jhodgdon’s picture

Great, thanks -- that looks good (and thanks for the explanation).

So, once again: It looks like webchick, xjm, Michelle, and Kristen Pol have agreed to the changes listed as "suggested changes" in the issue summary. Tor Arne Thune, yoroy, and catch agreed to the proposal in #24, which was not quite the same standard.

So I think we should leave this at RTBC for a couple of days and see if there area any further discussions/ideas/objections, and then edit the pages listed in the Suggested Changes in the issue summary if everyone is in agreement.

Tor Arne Thune’s picture

In #36 I agreed to #33 as well.

yoroy’s picture

No objections to the refinements made, please go ahead :)

jhodgdon’s picture

Thanks - missed that. :)

yoroy and catch - any comments?

As a note, we will also need to make a patch to update the .info files and hook_help() for a few core modules in Drupal 8 (at this point, too late to change for Drupal 6/7)... let's see:

contextual/contextual.info:name = Contextual links
dblog/dblog.info:name = Database logging
php/php.info:name = PHP filter
translation/translation.info:name = Content translation
update/update.info:name = Update manager

And a number of the test-only modules do not follow this convention either.

jcisio’s picture

I don't think we need to fix those .info files now. They are harmless and they will be changed when some body touches them.

xjm’s picture

Disagree with #48. It's a simple patch and we might as well do it all at once so that it gets done. Also, doing such cleanups as part of other issues is scope creep.

Kristen Pol’s picture

I agree with @jcisio that the existing module names shouldn't be changed as part of this policy change. Perhaps another issue could be created that addresses that directly.

Changes in #43 look good to me.

Kristen

jhodgdon’s picture

I also disagree with #48. If we create a new standard and don't start by modifying Drupal Core so it follows the standard, then new contributed modules will not notice the standard or follow it. We can have a separate issue to make the patch, but it does need to be done.

xjm’s picture

arianek’s picture

Just got a ping for this, many days late, but y'all have already sorted it out exactly the way it should be. Holy annoying to change it all through the docs, but that's how it should have been all along. "Foo Bar Whee module" +1

DamienMcKenna’s picture

As the child of a teacher, +1 for Proper Name Case module names to follow proper English spelling rules.

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Ok, let's call this fixed. See everyone at #1430452: Use Proper Name Case for core modules.

jhodgdon’s picture

Assigned: Unassigned » jhodgdon
Status: Fixed » Reviewed & tested by the community

Maybe we can leave it at RTBC until the docs have been updated? I'll assign to myself to change them (tomorrow first thing).

jhodgdon’s picture

Status: Reviewed & tested by the community » Fixed

The three standards docs pages above have been edited:
http://drupal.org/node/542202 (.info files)
http://drupal.org/node/604342 (UI text)
http://drupal.org/node/632280 (module help)

klonos’s picture

Status: Fixed » Active

...just as an addition, the standard should note that names which

- suggest usage or integration of 3rd party libraries/projects/services
- are acronyms

should be excluded from the standard.

So modules/themes that include 3rd party proper names in their name should use the exact capitalization the respective 3rd party authors use for their projects.

Examples:

CSS Injector - not Css Injector
jQuery Update - not Jquery Update
Views UI - not Views Ui
WYSIWYG - not Wysiwyg
...(more???...)

jhodgdon’s picture

Status: Active » Fixed

True... That should be fairly obvious, but I have no objection to adding it to the standard. I also don't think we need to discuss it for adoption, since it's just standard English usage rules.

So I went ahead and added a short note about trade names and acronyms to
http://drupal.org/node/604342
http://drupal.org/node/542202

xjm’s picture

http://drupal.org/node/1075072 also needs to be updated I think.

Edit: jhodgdon has fixed that doc now. :)

klonos’s picture

Thanx for your prompt actions Jenifer. One minor thing though: "jQuery" (no capital "j") is how the authors capitalize it - not "JQuery" as you have it in the docs you've updated.

jhodgdon’s picture

Fixed - thanks!

Automatically closed -- issue fixed for 2 weeks with no activity.

Anonymous’s picture

Issue summary: View changes

Removed original report