Code Formatting Organisation Discussion

[dongrentianyu]

I often deepen my understanding of TiddlyWiki by studying the core entries, but I find that a lot of the code doesn't have a strict format. It doesn't. Some like single quotes, some like double quotes, some like line breaks, some like spaces, some like tabs. of course there are times when we need to use a mix of single quotes and double quotes, but this should be used in special cases, not universally at random.

I think a code formatting specification should be introduced in version 5.4.0. ME. Or we could develop a specialised plugin to do such a thing, I've been looking forward to such a tool.

[pmario]

Which "code" you mean. TW WikiText or the core JavaScript code?

For the core JS code we plan to implement a pretty-printer, which does the formatting automatically.

For the WikiText code the "rules" are more relaxed, since we do have a lot of UI code, that dates back to 2014 or earlier. Where we did not really know, what the requirements would be in 2025. So most of that UI code did grow organically and was written by different contributors. So it is natural, that there are differences.

Also in earlier TW versions it was not possible to have newlines within widget parameters, so it was common to have very long lines. Now we can have line breaks, almost everywhere.

With the TW core we use

• double quotes for strings and parameters.
• triple double quotes if a string does contain a double quote.
• single quotes are an exception, for edge cases, if there is no other way.

Indentation is done using TABs, because we ship the UI and JS source code as plain text. So it needs less memory.
An exception is WikiText, that was generated by users, using the TW editor. Since there is no TAB key / button, we also allow indentation with 2 spaces per level. But if the code is maintained, space are generally replaced with tabs.

So "new style" wikitext code looks like this. eg:

TiddlyWiki5/core/ui/SideBar/Tools.tid

Lines 1 to 27 in e8a7bbf

	title: $:/core/ui/SideBar/Tools
	tags: $:/tags/SideBar
	caption: {{$:/language/SideBar/Tools/Caption}}
	\whitespace trim
	\procedure lingo-base() $:/language/ControlPanel/
	\function config-title() [[$:/config/PageControlButtons/Visibility/$(listItem)$]substitute[]]
	<<lingo Basics/Version/Prompt>> <<version>>
	<$let tv-config-toolbar-icons="yes"
	tv-config-toolbar-text="yes"
	tv-config-toolbar-class=""
	>
	<$list filter="[all[shadows+tiddlers]tag[$:/tags/PageControls]!has[draft.of]]" variable="listItem">
	<div class={{{ [<listItem>encodeuricomponent[]addprefix[tc-btn-]] tc-sidebar-tools-item +[join[ ]] }}}
	data-title=<<listItem>>
	>
	<$checkbox tiddler=<<config-title>> field="text" checked="show" unchecked="hide" default="show" class="tc-tiny-gap-right"/>
	<$transclude $tiddler=<<listItem>>/>
	<i class="tc-tiny-gap-left tc-muted">
	<$transclude $tiddler=<<listItem>> $field="description"/>
	</i>
	</div>
	</$list>
	</$let>

[pmario]

With TW we use tab-size 4. Here at GH it somehow uses tab-size 8. So it looks different.

[dongrentianyu]

I was referring to wikitext. considering that version 5.4.0 is a relatively large version update, I think it could fix some of the early TW code formatting mess. I'm not a programmer and don't know what code formatting specification would be better, but I think we need one.

Another thing is, maybe consider reducing the length of tabs, as there are times when the code looks long and not very easy to read.

I'm not sure if this is something to discuss in the forums, maybe it's worth discussing. But then everyone's preferences are not quite the same and it might be difficult to come up with a definite solution.

[pmario]

I was referring to wikitext. considering that version 5.4.0 is a relatively large version update, I think it could fix some of the early TW code formatting mess.

The main problem is, that with wikitext by default "white-space has a meaning". That's why we need to use \whitespace trim quite a lot. Otherwise we will create unwanted whitespace in the DOM structure.

The other problem is, that changing existing wikitext code into "new code" is not trivial. So it will need to be a 2-step wrokflow.

• First: Add indentation and make sure, that functionality does not change
• Second: Implement the "new syntax" without breaking too many 3rd party plugins

[kookma]

I think a code formatting specification should be introduced in version 5.4.0.

I fully support this. While wikitext offers flexible formatting, for those merged into the core in TW5.4.0, we should at least have best practice recommendations.

[pmario]

I did create a new issue:

• DEV Edition - Code Formatting Best Practice Documentation #9176