code-folding vs. comment-folding

[sjorek]

The current implementation offers the ability to fold comments by using a language-dependent prefix called foldPrefix in the comment to collapse.

It's somehow confusing, as one could think only the comment gets folded, but actually the whole segment including all the code that follows the comment, up to but not including the next comment gets folded. The current “excuse” for this behavior are use cases, like hiding unimportant code as in node.js-imports, i.e.:

# ^ imports: (<= start to fold here …)
foo = require 'bar'
blah = require 'bulb'

# (… folding stops above)
… more code …

It's time to conceive ideas on how to optimize the current implementation, and we encourage you to comment on that. The first ideas follow this comment.

[sjorek]

Idea No. 1: use different prefixes

We could use different prefixes to differentiate code- from comment-folding.

Let's assume we have a prefix like ^ for comment-folding and a prefix like ] for code-folding.

Hint: all examples use coffee-script syntax.

Example: single-line comment-folding

# ^ <= start to fold here … useful for very long comments … and immediately stop folding here =>
# (… folding stops above)

Example: multi-line comment-folding

### ^ <= start to fold here
… and immediately stop folding after finishing the block comment below
###
# (… folding stops above)

Example: single-line code-folding

# ] <= start to fold here
… some code or embedded comments
# … folding stops above, as this is a new segment

Example: multi-line block-comment code-folding

### ] <= start to fold here
#  
###
… some code or embedded comments
# … folding stops above, as this is a new segment

Pros:

• The simplest solution
• Compared to idea no. 2 it does not need an additional stop mark cluttering the code.

Cons:

• The user might need to add a useless comment to stop code-folding
• If one wants to embed comments in the folded area, he/she must use the additionally comment-embedding prefix
  known as ignorePrefix

[sjorek]

Idea No. 2: Mark the start and stop of the segment to fold with different marks

We could use one prefix to mark the start of the segment to fold and a different one to stop folding. Let's assume we have a start-mark like ] and a stop mark like ^ (Beware I deliberately changed the order to avoid markdown-clashes).

Hint: all examples use coffee-script syntax.

Example: single-line comment-folding

…
# ] <= start to fold here … useful for very long comments … and immediately stop folding here => ^
…

Example: in block-comment comment-folding

… some code …
### ] <= start to fold here
… some block-comment content … ^ <= folding stops here, right within the block-comment
… some more block-comment content that must be embedded 
    into code, due to the folding above …
###
… some code …

Example: single-line code-folding

…
# ] <= start to fold here
… some code or embedded comments, included in the folded segment
# ^ … folding stops on the line before this comment 

    …

Example: single-line code-folding

…
# ] <= start to fold here
… some code or embedded comments
# … folding stops on this comment-line => ^
…

Example: multi-line block-comment code-folding

…
### ] <= start to fold here
… some block-comment content …
###
… some code or embedded comments, included in the folded segment
# ^ … folding stops on the line before this comment 
…

Pros:

• The user has full control
• Compared to idea 1, one must not use the additionally comment-embedding prefix known as ignorePrefix, to
  include comments in the area to fold.

Cons:

• Needs an additional stop-mark that clutters the code

[sjorek]

Idea No. 3: Provide a code-folding feature with a smart end-of-fold-detection.

This idea could be combined with a unique prefix as in the code-folding part of Idea (1). So the implementation could be enhanced as follows:

1. We record the indent of the comment that starts the folding, to use it that as a reference.
2. We collect the whole comment. (Up to this point it is identical to the current implementation).
3. After the comment we compare the reference-indent's length/size with those of the following code-lines

• If the reference indent is greater than the current line's indent but not greater than the initial indent,
  we collect the current line as part of the area to fold
• If the reference indent is greater than the current line's indent and smaller than or equal to the initial indent,
  we stop folding at the previous line
• If the reference indent is equal to the current line's indent,
  we collect the current line as part of the area to fold
• If the reference indent is smaller to the current line's indent,
  we collect the line as part of the area to fold and
  use the current line's indent as the “reference indent”
• (Optional: If the reference indent is equal to the current line's indent but the current line is empty,
  we stop folding at the previous line)

As a result we could have the following behavior, assuming we use ] as the start-to-fold marker.

Hint: all examples use coffee-script syntax.

Example 1:

# ] <= start to fold here … the reference indent is the empty string `''` and has a length of `0`
if condition            # … the reference indent is the empty string `''` and has a length of `0`
   … some code          # … the reference indent is the string `'  '` and has a length of `2`
else                    # … the reference indent is the empty string `''` and has a length of `0`,
                        #   hence folding stops on and includes the line before the `else`-statement
   … some code

Example 2:

if( condition ) {
   # ] <= start to fold   … the reference indent is the string `'  '` and has a length of `2`
   … some code          # … the reference indent is the string `'  '` and has a length of `2`
} else {                # … the reference indent is the empty string `''` and has a length of `0`,
   … some code          #   hence folding stops on and includes the line before the `else`-statement
}

Example 3 (a single comment)

some code …
   # ] <= start to fold   … the reference indent is the string `'  '` and has a length of `2`
more some code          # … the reference indent is the empty string `''` and has a length of `0`,
… some code             #   hence folding includes only the single-line comment

Pros:

• Does not need an end-mark
• Does not fold parts that obviously do not belong to each other

Cons:

• It heavily depends on the code-formatting and -quality

Suggestions:

• could be an optional strategy enabled by command-line option or project-configuration-file

[sjorek]

Idea No.4: Never fold code

It could be a bad idea to fold areas that include code. Folded areas should not hide code (or any other information) from the readers eyes. It's not the authors task to decide what's important to the reader and what not …

Pros:

• Easily implementable

Cons:

• We loose a currently established feature

Suggestion:

• Make this behavior configurable via command-line or project-configuration-file

[sjorek]

@achingbrain + @kmdavis and all the others are welcome to bash this topic … 💥 …

[sjorek]

… last updated: 09/18/2013, 07:00 PM, +0100 CEST

[achingbrain]

The idea behind my original pull request was to be able to hide code, so I think it would be a shame to see that go away. Imports and the like are dull and distract the reader from the interesting bits.

I also wanted "private" methods to be not immediately visible (although still available for the interested reader) - I know this is not strictly inline with the idea of literate programing but I think the tradeoff for readability is worth it.

I'm not a big fan of the idea of having open-folding-section and close-folding-section comments. I think just "this comment documents the following code" is enough - if that comment decides to hide the following code, so be it. The next comment encountered should say something useful about the code following it, so it's enough to end the folding block.

If you feel you're having to contort your comments to un-hide a block, perhaps you should instead write something useful in your comment as to why the next bit of code deserves the reader's attention ;)

[sjorek]

Phew, good to know that my last change to the master's HEAD, didn't change the intended behavior ! 😁

… I agree with your intention, but I've also found several use cases (I'll show them later, if you want to) where too much code was hidden (eg. spanning if- and else-statements and the [falsely] undocumented following method). So we still need a better way control this behavior. And what if I really just want to fold an overlong comment and nothing else ?

[sjorek]

I'm going to make a break for today and watch back tomorrow … bye … 👋