Improved comment syntax
complete
T
Tim Mackey
Liquid's default comment syntax is "pig ugly", as another mechanic user so succinctly put it. The usability of tasks in the task library could be greatly improved with better code commenting. However, the built-in comment format is a huge impediment to readability. I propose that a new comment syntax is created, with the goal of simplifying the writing of comments and improving readability.
"Blade style" comments is one syntax that has been suggested:
{{-- This is a nicer comment --}}
Personally, as I spend a lot of time in a JavaScript environment, I like having the option of both inline comments and block comments (although the specific syntax wouldn't work in liquid). e.g.:
// inline comment
/*
block comment
*/
I'm especially partial to JSDoc comments, as they are really good for explaining blocks of code and the convention of having an
*
at the beginning of each line helps to visually separate the comment from the rest of the code. e.g.:/**
* Convert a string containing two comma-separated numbers into a point.
* @param {string} str - The string containing two comma-separated numbers.
* @return {Point} A Point object.
*/
static fromString(str) {
// ...
}
Isaac Bowen
complete
Done. :)
https://mechanic.canny.io/changelog/liquid-54-featuring-inline-comments-and-the-liquid-tag
C
Charles Akben-Marchand
I'd love it if I could type an apostrophe or other punctuation in a Mechanic Liquid comment and not have the rest of my comment change colour! ;)
Isaac Bowen
Tim Mackey Thank youuuu for thinking about this. I agree that this is important, but I think Liquid core is about to beat us to it, which is several kinds of perfect. :D
Tobi (progenitor of Liquid) started a convo back in January about a syntax for this sort of thing:
... resulting in this (currently open) pull request:
... which I
think
is going to be merged soon. It looks like it's nearing that point. If/when it merges, Liquid will natively
have support for comments using this syntax:{% # Single line comment %}
{% liquid
echo "..."
# Works well for single line comments
# or even multi-line comments
echo "..."
%}
Matt Sodomsky
Isaac Bowen: awesome! Thank you for the update Isaac Bowen
T
Tim Mackey
Isaac Bowen: Whoah, Tobi must be reading this forum, because he made his proposal the same week as this post 😉
T
Tim Mackey
I've been thinking about possible syntax for comments, and these are the two options that I've been leaning towards...
{{-- This is a line comment --}}
{{--
This is a block comment
--}}
{* This is a line comment *}
{*
This is a block comment
*}
Either of these would work as both single-line or block comments. I'm not sure whether either of these would cause issues with syntax parsing, but I've set them up with code highlighting in VSCode and haven't run into any problems yet.
Matt Sodomsky
under review