Naming rules and the best practice : from wikitext scripting point of view

[Atronoush Parsi]

I have followed recent discussion on naming the fields or tiddlers in the Google Forum! I wish to know are there recommendations for this?

• tiddler name
• field name
  
• macro name
• variable name
• by $set
• by $vars
• by $list
• by $wikify
  
• css selector
• global and local

I am not sure but I assume Tiddlywiki does not have support for namespace! but I see TW honors scope of variables!

I was complaining about the currentTiddler name! Now I understand how much it is meaningful! albeit with TW 5.122+ specially in TW 5.1.23 and 5.1.24p we have much more flexibility in scripting

but the default is very meaningful!

I see from TW official docs and codes, it uses

tv- prefix for variable

tc- prefix for some CSS selectors

How can we use a naming rule to develop more readable scripts and wikitexts?

I appreciate your advice!

--Atro

[PMario]

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

I see from TW official docs and codes, it uses

tv- prefix for variable

tc- prefix for some CSS selectors

tv- ... tiddlywiki variable

tc- ... tiddlywiki class

tm- ... tiddlywiki message

These prefixes are reserved for "the core". Users, especially plugin authors should avoid to use them. .. They should only used, if pull-requests for the core are pushed to github.

I personally use, wltc-, wltc-, wltm- ... wl .. for wikilabs ... So I know they are part of a plugin, but my users will still get, what they are used for.

-m

[PMario]

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

I have followed recent discussion on naming the fields or tiddlers in the Google Forum! I wish to know are there recommendations for this?

• field name
  

There are some restrictions for tiddler field-names.

"Field names must be lowercase letters, digits or the characters - (dash), _ (underscore) and . (period)." .. from the docs.

-m

[PMario]

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

...

I am not sure but I assume Tiddlywiki does not have support for namespace! but I see TW honors scope of variables!

We do use the term: "namespace" .. but probably in a different context as you mention here. eg:

$:/temp/ ..

 - Is a namespace for temporary variables, which don't trigger an automatic save

 - Such tiddlers are used like "variables" in other languages.

 - They are easy to filter eg: {{{ [prefix[$:/temp/]] }}}

The "Explorer" shows all the System namespaces. https://tiddlywiki.com/#%24%3A%2Fcore%2Fui%2FMoreSideBar%2FExplorer

-mario

[PMario]

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

I have followed recent discussion on naming the fields or tiddlers in the Google Forum! I wish to know are there recommendations for this?

• variable name
  • by $set
  • by $vars
  • by $list
  • by $wikify
    

Good question. ... The universal answer. ... It depends ;)

I think the most important thing is, that you use _good_ names, that explain "what they do" or "what they contain" 

What I use for variables:  config-title, config-filter

eg:

\define getConfigTitle() $:/temp/$(currentTiddler)$

\define config-filter() [tag[config]]

<$list filter=<<config-filter>> >
  <$macrocall $name="a-macro" title=<<getConfigTitle>> />
  <<currentTiddler>> -> <<getConfigTitle>>
</$list>

If a tiddler title is dynamic and I need to build it with at macro I use getConfigTitle() for the macro. So I know, whenever there is a getSomething() there will be variable substitution involved. ...

For other variables I prefer lowercase-lowercase-lowercase  to increase readability and I don't have to think about "case".

But as I wrote: The most important thing is "good names" ... which is the difficult part ;)

mario

[TW Tones]

Mario,

You say $:/temp/ .. - Is a namespace for temporary variables, which don't trigger an automatic save.

If I can do without periodical saves, on a particular large tiddler, should I be importing large files or tiddlers (data plugin) and renaming them with the $:/temp/ prefix so as I make changes on this large tiddler I get improved performance, if it is not saved on every change?

Rather than renames to $:/temp/ perhaps changing the save filter to not save tiddlers with say a temp tag, or field etc... would be easier?

Regards

Tones

[Mohammad Rahmani]

Very good discussion!

Having some good practice helps improve readability of the Tiddlywiki scripts! One problem I always have is reading codes especially those with several tiddlers and I found it quite difficult to follow!

@Mario

- semantic names as you suggested are very helpful

- the prefix like tv- for variable! It would be great to distinguish here between different type of vars

- global and local vars and scope is also one area of confusion! a global var in a tiddler scope is one defined using \define

  and out of scope is the one is defined using \define in a tiddler tagged with $:/tags/Macro

- overloading macros and variable is a great feature of Tiddlywiki worth more discussion

Maybe we could benefit of documents on Javascript, as I believe TW Scripts is high level language comparing to JavaScripts

I try to get idea from W3C JavaScripts best practice: https://www.w3.org/wiki/JavaScript_best_practices

Best wishes

Mohammad

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/8f429e9b-cb56-45b3-bfff-d192f091f904n%40googlegroups.com.

[TiddlyTweeter]

Ciao all

A general comment. 

TW is nomothetically agnostic on nomenclature. 

It has no Naming Police checking coding.

I am NOT sure that a totally consistent shared method is possible?

Rather, it is more like individuals, who are doing a LOT of coding benefit from having their OWN naming schema?

JUST a comment, TT

[Mohammad Rahmani]

This may be also helpful

https://en.wikipedia.org/wiki/Hungarian_notation

Best wishes

Mohammad

--

You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/dcae536e-7db2-4bc8-91f3-0b90c2484d2en%40googlegroups.com.

[Mohammad Rahmani]

Performance

Coding conventions are not used by computers. Most rules have little impact on the execution of programs.

Indentation and extra spaces are not significant in small scripts.

For code in development, readability should be preferred. Larger production scripts should be minified.

From: https://www.w3schools.com/js/js_conventions.asp

 

Best wishes

Mohammad

[PMario]

On Thursday, May 6, 2021 at 3:08:27 PM UTC+2 Mohammad wrote:

...

For code in development, readability should be preferred. Larger production scripts should be minified.

In TW the whole core is plain text, because it makes it easy to debug the app, without any additional tooling, and some "basic" knowledge. The browser itself is enough.

If the core would be minified, I personally wouldn't want to dig into a "buggy" wiki that is hosted on the web and a user asks for help. ... With the existing "core" there is no problem. You go there and can start having a look. ... No time wasted for preparing something. ..

In the meantime it is possible to "minify" the core. ... But a proper server side "compression" setting imo does the same job and allows the community to be "productive" in terms of maintenance ;)

just some thoughts

-mario

[Mohammad Rahmani]

It Seems Tiddlywiki has a total liberty in naming rules. 

Open Tiddlywiki and put this code in a Tiddler! See all of them world!

\define .() test

Hi. This is <<.>>

<$vars
 _var   =Hi
 1var   ="Hello"
 fr.var ="Salut"
 .      ="Salve"
 )*&    = "konnichiwa"
 !var   = "Olá">
 
 * _var: <<_var>>
 * 1var: <<_var>>
 * fr.var: <<fr.var>>
 * . : <<.>>
 * $*&): <<)*&>>
 * !var: <<!var>>
 
 </$vars>

Strangely (or amazingly!!!) all of them work! You can even name a variable like  )*&

Is this a sign of pure forgiveness? Or something has been forgotten? Or this is a design philosophy?

While most users do not need in depth scripting but I believe most of the above are error prone!

What do you think? I think we need some coding conventions? Some good practice at least!

Best wishes

Mohammad

--

You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/CAKHVXmqmwSkk%2B5Zq%3D81voVE%3DJQVM6U11ucpaLpbw14YCRhUD7Q%40mail.gmail.com.

[Atronoush Parsi]

Hi Mario,

 I appreciate your detailed discussion and recommendations. The use of wltc and wltm are good practice!

 

On Wed, May 5, 2021 at 9:56 PM PMario <pmar...@gmail.com> wrote:

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

I see from TW official docs and codes, it uses

tv- prefix for variable

tc- prefix for some CSS selectors

tv- ... tiddlywiki variable

tc- ... tiddlywiki class

tm- ... tiddlywiki message

These prefixes are reserved for "the core". Users, especially plugin authors should avoid to use them. .. They should only used, if pull-requests for the core are pushed to github.

Correct!

I personally use, wltc-, wltc-, wltm- ... wl .. for wikilabs ... So I know they are part of a plugin, but my users will still get, what they are used for.

-m

--

You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/9354a29a-d11e-405a-bf1c-1c660a70cc51n%40googlegroups.com.

[Atronoush Parsi]

On Wed, May 5, 2021 at 10:08 PM PMario <pmar...@gmail.com> wrote:

On Wednesday, May 5, 2021 at 4:53:25 PM UTC+2 Atronoush wrote:

...

I am not sure but I assume Tiddlywiki does not have support for namespace! but I see TW honors scope of variables!

We do use the term: "namespace" .. but probably in a different context as you mention here. eg:

$:/temp/ ..

 - Is a namespace for temporary variables, which don't trigger an automatic save

 - Such tiddlers are used like "variables" in other languages.

 - They are easy to filter eg: {{{ [prefix[$:/temp/]] }}}

I have seen this alot for plugins and it is good practice here!

I see on Node.JS both $:/temp and $:state will be deleted on exit! If one wishes to keep data permanently do you recommend

something like $:/keep/state?

The "Explorer" shows all the System namespaces. https://tiddlywiki.com/#%24%3A%2Fcore%2Fui%2FMoreSideBar%2FExplorer

-mario

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/46f6a2eb-6640-4b09-91ee-0e09f6884f42n%40googlegroups.com.

[Atronoush Parsi]

On Wed, May 5, 2021 at 10:35 PM PMario <pmar...@gmail.com> wrote:

I think for variables, this lowercase-lowercase-lowercaseis great!

for macros, which creates global variables in scope of a tiddler, I prefer your camelCase naming! I think this is better than PascalCase!

I saw a recommendation not to use hyphens and use underscores instead! Especially in Python we cannot do this!

Many other languages do no not allow hyphens, but I see in Tiddlywiki it is quite common and we have the same in CSS

like font-size! So I go for this!

 

But as I wrote: The most important thing is "good names" ... which is the difficult part ;)

Yes, this is very difficult!

mario

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/8f429e9b-cb56-45b3-bfff-d192f091f904n%40googlegroups.com.

[Atronoush Parsi]

On Thu, May 6, 2021 at 6:15 PM Mohammad Rahmani <mohammad...@gmail.com> wrote:

It Seems Tiddlywiki has a total liberty in naming rules. 

Open Tiddlywiki and put this code in a Tiddler! See all of them world!

\define .() test

Hi. This is <<.>>

<$vars
 _var   =Hi
 1var   ="Hello"
 fr.var ="Salut"
 .      ="Salve"
 )*&    = "konnichiwa"
 !var   = "Olá">
 
 * _var: <<_var>>
 * 1var: <<_var>>
 * fr.var: <<fr.var>>
 * . : <<.>>
 * $*&): <<)*&>>
 * !var: <<!var>>
 
 </$vars>

Strangely (or amazingly!!!) all of them work! You can even name a variable like  )*&

Is this a sign of pure forgiveness? Or something has been forgotten? Or this is a design philosophy?

While most users do not need in depth scripting but I believe most of the above are error prone!

What do you think? I think we need some coding conventions? Some good practice at least!

This is absolutely bad practice! I believe TW should raise warning for these specially names like , 

or even the worst case $*&)

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/CAAV1gMAjiKK%2B9Lis-bA1sShFMOLfmu%3DBZAwveDYNqb2tbtH7Cw%40mail.gmail.com.

[PMario]

On Thursday, May 6, 2021 at 6:52:02 PM UTC+2 Atronoush wrote:

I see on Node.JS both $:/temp and $:state will be deleted on exit! If one wishes to keep data permanently do you recommend

something like $:/keep/state?

You are right. The node-version doesn't save $:/temp and $:/state... The single-file version _does_ save $:/state. It only skips $:/temp tiddlers.

There is a configuration option, what and how tiddlers can be saved with node: Have a closer look at: https://tiddlywiki.com/#Customising%20Tiddler%20File%20Naming:%5B%5BCustomising%20Tiddler%20File%20Naming%5D%5D%20%5B%5BTiddlyWiki%20on%20Node.js%5D%5D

So it will be possible to save $:/state if you want them. So there is no need to invent your own prefix. ... BUT $:/keep/state will be saved without any additional configuration.

So you can decide.

-m

[PMario]

On Thursday, May 6, 2021 at 7:21:31 PM UTC+2 Atronoush wrote:

I think for variables, this lowercase-lowercase-lowercaseis great!

for macros, which creates global variables in scope of a tiddler, I prefer your camelCase naming! I think this is better than PascalCase!

Yea, I use Hungarian notation for macros, because Camel/PascalCase will create an automatic wikilink, if you use that name in the docs, which most of the time isn't what I want. ..

 

I saw a recommendation not to use hyphens and use underscores instead! Especially in Python we cannot do this!

Yes, but wikitext is not Python ;) .. I personally prefer hyphens over underscores. .. But this is just my preference.

 

Many other languages do no not allow hyphens, but I see in Tiddlywiki it is quite common and we have the same in CSS

like font-size! So I go for this!

Right. We have to be more liberal here. Our main "customers" are ordinary users and not programmers :)

-m

[PMario]

On Thursday, May 6, 2021 at 3:45:52 PM UTC+2 Mohammad wrote:
Strangely (or amazingly!!!) all of them work! You can even name a variable like  )*&

Is this a sign of pure forgiveness?

That's intentional.

 

Or something has been forgotten? Or this is a design philosophy?

Philosiphy.

 

While most users do not need in depth scripting but I believe most of the above are error prone!

Sometimes it may cause problems. ... But for some usecases, we don't know, it may be the only way to create a simple solution. .. So limiting the possibilities will do more harm, than good, in the long run.

I think it's about "choice". The user has the choice. ... They can decide if it works for them or not.

 

What do you think? I think we need some coding conventions? Some good practice at least!

hihi, ... Talking about "coding conventions" is like "talking about religion" ... I think some examples and a little bit of "best practice" is the way to go.

On Thursday, May 6, 2021 at 7:22:54 PM UTC+2 Atronoush wrote: 

...

This is absolutely bad practice! I believe TW should raise warning for these specially names like , 

or even the worst case $*&)

We do raise a warning for tiddler titles, if you use brackets, because they can cause problems in filter syntax. But since most operators can handle variables, even this shouldn't be a problem anymore. ..

What's the difference between )*& and "хелло-wорлд" ... Both strings look strange for me. But for someone who can read it, it's perfectly fine.

You are right. Brackets can make problems. ... But the rest should be fine.

-mario