[TW5] Naming conventions for tiddlers, classes, tags, etc.

[Novan Leon]

I've noticed the following naming conventions present in TW5:

• Root namespaces all appear to be lowercase, with no exceptions.
• System tiddlers use a variety of different naming conventions including lowercase, hyphen-case, CamelCase or a mixture of the three as explained here. I'm not sure what the rationale for the chosen convention is in each namespace though.
• Classes almost always begin with a two-letter prefix such as "tc" or "tm" followed by the class name which sometimes includes hyphens and sometimes not.
• System tags appear to always use CamelCase but can included slashes ("/") for hierarchy, such as $:/tags/AdvancedSearch/FilterButton.
• Field names are always lowercase or hyphen-case.
• Widgets and macros always appear to be lowercase or hyphen-case.
  
• It appears state tiddlers are sometimes specified with compoundCase, such as $:/state/filterDropdown.
  

I was wondering if there was an established rationale behind these naming conventions? Are there specific situations where you would choose to use CamelCase instead of lowercase, or lowercase instead of hyphen-case, for example? If so, is this naming convention explained anywhere for us to reference?

I'd like to follow the established conventions as much as possible, if they exist.

[PMario]

On Friday, February 17, 2017 at 10:37:44 PM UTC+1, Novan Leon wrote:

I've noticed the following naming conventions present in TW5:

• Root namespaces all appear to be lowercase, with no exceptions.

right

• System tiddlers use a variety of different naming conventions including lowercase, hyphen-case, CamelCase or a mixture of the three as explained here. I'm not sure what the rationale for the chosen convention is in each namespace though.

I think it's a grown structure and when TW reched beta-state, only decisions that really caused bad problems where changed.
At least the stuff is consistent per namespace.
 

• Classes almost always begin with a two-letter prefix such as "tc" or "tm" followed by the class name which sometimes includes hyphens and sometimes not.

Those prefixes are there, so that TW doesn't use eg: class names, that would be chosen by users for there own classes. eg: TW uses: tc-body or tc-title instead of body or title. So end-users can use them. ...

for plugin authors it makes sense to use their own prefixes. So they won't clash with other plugins. ... eg: I may use pmtc- pmtm- and so on.

tc- ... tw class
tm- ... tw message
tv- ... tw variable

see: http://tiddlywiki.com/#Release%205.0.16-beta  

Important: Plugin authors should reuse existing tc-  classes if possible. So plugins will auto-adjust to color-palette settings and themes.

... BUT if new classes are needed, they should be prefixed like pmtc- ... So everyone knows, that pmtc- is not part of the core. Some authors don't follow this rule. So we need to tell them!

• System tags appear to always use CamelCase but can included slashes ("/") for hierarchy, such as $:/tags/AdvancedSearch/FilterButton.

"/" for hierarchy ... we call it namespace. eg: $:/config/ .. namespace

Most of the "user facing" elements use CamelCase. .. stuff that's core internal is likely to be lowercase or hyphen-case
 

• Field names are always lowercase or hyphen-case.

They have to be lowercase. That's a technical restriction, that's dictated by browsers. Field names are stored as html attributes in the tiddlywiki.html file. CamelCase field names don't survive a "save/reload" cycle. There are discussions to change that, but it hasn't happen yet.

• Widgets and macros always appear to be lowercase or hyphen-case.
  

yes. lowercase for consistency and hyphen-case for readability.

• It appears state tiddlers are sometimes specified with compoundCase, such as $:/state/filterDropdown.
  

I think that's only consistent within the namespace. .. but different namespaces depend on the usecase and how they have evolved over time.
 

I was wondering if there was an established rationale behind these naming conventions?

I tried to name them. But as I wrote. .. The stuff has evolved over time and since version 5.1.0 ... they are locked for backwards compatibility.
 

Are there specific situations where you would choose to use CamelCase instead of lowercase,

IMO if they are end-user facing CamelCase may be used for tiddlers and readability
sometimes lowercase has to be used: ... for field names. So field names use hyphen-case
 

or lowercase instead of hyphen-case, for example?

I personally use mixedCase for internal variables. So something that's not intended to be changed by the user, but by the program.
 

If so, is this naming convention explained anywhere for us to reference?

not really. ... But you may point to this discussion from now on :)
 

 

I'd like to follow the established conventions as much as possible, if they exist.

 
IMO there are some key points.

 - consistency (per namespace)
 - readability
 - don't use names (eg: for core styles), that may be used by end-users or other plugin-authors

hope that helps.

have fun!
mario

[PMario]

On Friday, February 17, 2017 at 10:37:44 PM UTC+1, Novan Leon wrote:

I've noticed the following naming conventions present in TW5:

As you found out. There are naming conventions. ... but every user or plugin-author should be free to create there own conventions. The core tries hard to stay out of the way. ... So that's why some names, and conventions seem to be "irrational", but they make sense. .... hopefully ;)

-m

[Novan Leon]

Thanks for your response.

I'm still working on developing a standard for consistency but here's what I'm following so far, in case anyone is curious:

• lowercase for root namespace
• CamelCase for project namespace and "core" tiddlers.
• CSS tiddlers follow the convention of the tiddler they accompany.
  
• lowercase and hypen-case for widgets, macros, buttons, images and tiddlers that will be embedded in another tiddler or aren't immediately visible to the user.
• Avoid mixedCase, except within JavasScript code of course (coding conventions are another topic entirely)
  
• lowercase and hyphen-case for CSS class names.

Examples:

• $:/projects/MyProject/MyTiddler
• $:/projects/MyProject/MyTiddler.css
• $:/projects/MyProject/Widgets/widget-one.js
• $:/projects/MyProject/Widgets/widget-two.js
• $:/projects/MyProject/Widgets/widget-two.css
• $:/projects/MyProject/Buttons/button1
• $:/projects/MyProject/Buttons/button2
• $:/tags/MyProject/Button
• $:/state/MyProjectDropdown