Editing Code folding (section)

==Conventions==
In order to support code folding, the text editor must provide a mechanism for identifying "folding points" within a text file. Some text editors provide this mechanism automatically, while others provide defaults that can either be overridden or augmented by the user.

There are various mechanisms, coarsely divided as automatic and manual – do they require any specification by the programmer? Folding points are usually determined with one or more of the following mechanisms. Each of these has its own distinct advantages and difficulties, and it is essentially up to the developers who create the text editor software to decide which to implement. Text editors that provide support for multiple folding mechanisms typically allow the user to choose which is most appropriate for the file being edited.

===Syntax-dependent===
Syntax-dependent folding points are those that rely on the content of the file being edited in order to specify where specific folding regions should begin and end. Syntax-based folding points are typically defined around any or all of the standard sub-features of the [[markup language]] or [[programming language]] in use. These are desirable due to being automatic and agreeing with code structure, but may require significant work to implement, and time to compute when editing a file.

===Indentation-based===
Indentation-based folding points are generally specified by the position and sequence of non-printing whitespace, such as tabs and spaces, within the text. This is most often used as a simple form of syntax-based folding, as indentation almost always reflects nesting level in [[indent style]]s for structured programming languages.

This convention is particularly suitable to syntaxes that have an [[off-side rule]], so the structure largely agrees with the indent. Examples include [[Python (programming language)|Python]] and text files that require indentation as a rule by themselves. However, even in these cases, structure does not exactly agree with indent, such as in [[line continuation]], and thus syntax-dependent folding is preferred.

===Token-based===
Token-based folding points are specified using special [[delimiter]]s that serve no other purpose in the text than to identify the boundaries of folding points. This convention can be compared to indentation-based folding points, where printable characters are used instead of whitespace. The most common delimiter tokens are <code>{{{</code> to begin the folded section, and <code>}}}</code> to end it.

Another notable token is <code>[http://msdn.microsoft.com/en-us/library/9a1ybwek.aspx #region]</code> ([http://msdn.microsoft.com/en-us/library/ed8yd1ha.aspx C# directives]), respectively <code>[http://msdn.microsoft.com/en-us/library/sd032a17.aspx #Region]</code> ([http://msdn.microsoft.com/en-us/library/7ah135z7.aspx Visual Basic directives]), used in [[Microsoft Visual Studio]] [[Microsoft Visual Studio#Code editor|Code Editor]]. These are treated syntactically as [[Directive (programming)|compiler directives]], though they do not affect compilation.

As a manual method, token-based folding allows discretion in grouping code based on arbitrary criteria, such as "functions related to a given task", which cannot be inferred from syntactic analysis.

Token-based folding requires in-band signalling, with folding tokens essentially being structured comments, and unlike other methods, are present in the source code and visible to other programmers. This allows them to be shared, but also requires their use (or preservation) by all programmers working on a particular file, and can cause friction and maintenance burden.

===User-specified===
User-specified folding allows the user to fold sections of text using a generic selection method, but without changing the source code (out-of-band), instead being specified only in the editor. For example, a programmer may select some lines of text and specify that they  should be folded. Folded text might be anonymous or named, and this may be preserved across editing sessions or discarded. Unlike token-based folding, this does not change the source text – it thus is not shared with other editors of the file, and is not visible in the code.