Comments in code - this is how we can do it.

[Mat]

As we know, it is currently problematic to add comments in wikitext code. This causes a lot of confusion even when I review my own code from a mere few days earlier - not to mention when reading someone elses code.

My current fiddling with EditorMagic sparked an idea: Would it be possible with code comments to be, not in the code, but as  "popups" that are not processed when the wikitext is processed? This illustrates the idea (the code snip is just arbitrary, never mind what it says, only look at the red things and the popups):

Like in EditorMagic, the popups are not part of the current editor content. When coding in wikitext, adding a generic <!> or <1>, <2>,... or some other marker, triggers a little popup editor where comments can be added. When the actual code is processed, such markers are jumped over. 

Actually, this approach even has several...

...advantages over in-line comments:

• The comments are kept separated - we could make a core annotations plugin!!! This should be super valuable for the whole TW project.
• It retains the compactness of the code.
• The popups could themselves show wikitext and be configurable, like the ambition for EditorMagic, to e.g include reference links or iframes.
• It would be simple to toggle the display of comments.

P.S As I, so far, somewhat clumsily illustrate in EditorMagic, the possibility to trigger popups in the editor that show arbitrary tiddler content is really a game changer for using the editor. I wish some of the big boys could make a proper js solution for this.

<:-)

[PMario]

Hi Mat,

A nice idea! ... But pardon me, being so harsh: It won't work. ...

As a developer I'd rather risk a performance hit using inline comments than maintaining 2 different sources of truth. Keeping them in sync will always fail.

-----------

What would be possible is a "pre-compile" step  while building TW. But this would only be available for a node based TW development setup, where the comments would automagically create a "comments-library" that could be imported to annotate the source code.

This annotation would need a special editor, that can handle the additional info. ... All of this "solutions" are way to complicated. So at the end I personally would go with "no comments" but proper indentation, which make the code more readable.

Creating PRs with, backwards compatible, indented core files and getting the changes merged is hard enough.

-mario

[PMario]

On Wednesday, April 8, 2020 at 1:46:50 PM UTC+2, PMario wrote:

... So at the end I personally would go with "no comments" but proper indentation, which make the code more readable.

BTW .. \whitespace trim  ... also has a performance impact.

-m

[Mat]

Thanks for your opinion Mario!

Do you have any suggestion for me - and probably the majority of the community - who find the current situation (including indentation) insufficient? It concerns both the core/standard distro and my own code.

<:-)

[TonyM]

Mat/Mario

I understand the concern about the source of truth but feel its possible to overcome this concern. I think mats idea has so much value its worth investigating. Let me share a concept I am working on.

Please bare with me as it will initially appear off topic.

I call it ghost tiddlers since shadow is taken. Basicaly it is a way of having one or more tiddlers behind any tiddler.

First imagin tiddlername having a matching tiddler $:/ghosts/tiddlername all annotations can go in this ghost tiddler. Now consider a field containing a unique tiddler serial number is used to link a tiddler to its ghosts so the tiddler title can change and retain the relationship to any ghosts. E.g. $:/ghosts/#sn/subtiddlername It is also possible to make a filter that can list a tiddler and all its ghosts for export. You could call these compound tiddlers.

With such compound tiddlers you could add content in this case annotations to the real tiddler via one or more ghosts. In effect giving you layered tiddlers.

I also discovered recently you can use tiddler serial numbers as you need them on demand.

Finally the view template can interrogate any tiddler with a serial number and locate and apply any ghost tiddlers at render time.

I hope this makes sense.

Regards
Tony

[TonyM]

Of course the annotations could go into fields.

Tony

[Mat]

Tony, I like your idea. Here's a sketch for a workflow/UI:

A'la EditorMagic, typing some trigger e.g <! could open a popup at caret position, showing a small floating editor. Comments are added there. Closing it converts the trigger into e.g <!-- # --> where # is e.g a calculated number unique within the tiddler (but another tiddler might have the same number). The number of comments a tiddler has is very limited so a rough but pragmatic strategy could be to number any new comment with "the current highest number +1".

Hovering or clicking this marker shows the comment. Or, clicking some button for the whole editview tiddler, opens all comments perhaps located where the preview area is located. (Nice if they're vertically located where the comment marker is but not sure if that's possible.)

What really happens as soon as you add a comment is that a ghost tiddler is created. Every new comment is a new field in this ghost tiddler. 

When a tiddler is deleted, its ghost tiddler should probably also be deleted. 

What happens if a comment marker is deleted? I guess saving the tiddler makes a run through of the existing markers and the existing ghostly comments and anything not matching up is removed.

Thoughts?

<:-)

[TonyM]

Mat,

A few thoughts

• Perhaps auto numbering is useful but manual numbering would be fine as well. 
• Yes actually I see this serial number method being useful in a number of places, multiple values for which one can obtain the next number. Keep in mind this needs a trigger to set the incremented field. 
• So when creating the ghost tiddler you need to either use or set then use the Serial number first.
• Rather than delete ghost tiddlers I suggest leave them, after all we could export and reimport and the matching serial number would come alive again. Of course if one was to delete large numbers of tiddlers an empty dead ghosts button would help reduce space wastage.
• Again if a comment marker is deleted leave the actual comment in the ghost tiddler, perhaps you are just cutting and pasting from one part of the tiddler to another. If the comment marker is restored it will return, you could have a list of orphaned comments to review if you wanted.

Further though should be given to global markers. 

• In this case they can be applied multiple times in multiple places and display the same content, wherever used. This would be good for annotating common code patterns, even ones you copied into your code from a code template, it could be preloaded with a global comment, perhaps even referencing the code pattern source. 
• Finally lets consider searching comments, find them in ghosts and listing the main non ghost tiddler.

Regards

Tony

[@TiddlyTweeter]

I fully agree with PMario.

Code is already abstract as far as I am concerned. Having to add complexity to get simplicity doesn't sound right.

Personally I'm crap at programming without copious inline comments since I quickly forget what does what without them. 

TW doesn't easily allow comments in code. Often its unworkable. 

I accept its part of my failure at getting better at it. But Mat's "solution" looks awkward and baroque IMO.

Non-starter for me, I think :-(. Sorry.

TT

[Mat]

@TiddlyTweeter wrote:

Mat's "solution" looks awkward and baroque IMO.

Ha! The thought of creating a baroque solution even sounds appealing.

What would you call a proposal for "no solution"?

<:-)

[@TiddlyTweeter]

@TiddlyTweeter wrote:

Mat's "solution" looks awkward and baroque IMO.

Mat wrote: 

Ha! The thought of creating a baroque solution even sounds appealing.

Well. I admire your vorpal sword anyway. 

What would you call a proposal for "no solution"?

Reality?

Actually you can kinda get part of the way there as is. But its a bit tricky.

There was a thread about it I'm trying to find ... 

Best wishes

TT

[@TiddlyTweeter]

Mat

Not sure how helpful it is (and there is no intent to trip-up your pony) but here is a brief past thread on comments in code. 

https://groups.google.com/d/msg/tiddlywiki/DBWzVqb2Xdo/KGgBDQRkCgAJ

I thought Eric's observations on the modest cases you CAN use an HTML comment tag very helpful. 

My final example using fake defines I not longer use much as its baroque :-)

Best wishes

TT

[Mat]

@TiddlyTweeter, appreciated even if the methods Eric mention are way to gritty for me to actually use. 

<:-)

[LinOnetwo]

This gives me a feeling of literal programming, that you can weave document and code together.

I think this kind of rich text comment is even more interesting. I think I will add lots of this kind of rich text comment to my code, even Javascript code.

在 2020年4月7日星期二 UTC+8下午7:33:33，Mat写道：

[Mat]

LinOnetwo wrote:

I think this kind of rich text comment is even more interesting. I think I will add lots of this kind of rich text comment to my code, even Javascript code.

Good to hear but I'm not quite sure how to implement it. A key thing is how the system would detect that one is hovering or clicking at a specific marker. If you're a js kinda guy then maybe you have some idea? Another idea might be right clicking, as per your idea elsewhere. I.e see comment in popup showne from right clicking.

<:-)