█ OVERVIEW
Follow these tips to help other Pine coders make the most out of your libraries.
Pine Libraries are open-source script publications containing functions intended for reuse by other Pine programmers. Introduced with Pine v5, they are transforming the landscape of the Pine community by making it easier for authors to share their most useful functions, and for other coders to reuse them. You will find more information on how to write and use a library in the Pine User Manual's page on libraries.
The whole point of libraries being that our community of Pine coders can use them, it follows that efforts to help others understand and use our libraries will be well spent. The following tips are good practices that will hopefully help you achieve this.
█ WRITING LIBRARIES
Scope
Clearly define your library's scope so users can quickly grasp what it's about. A library's scope may be technical analysis, array-handling, math calculations, etc. Avoid libraries containing a large number of functions, unless they cannot be divided into meaningful scopes. Single-function libraries are fine, as are ones containing only a main function and a few helper functions. You can always add functions to an existing library by updating it.
Naming
Carefully choose your library's name. It cannot contain spaces, so camelCase should be preferred. First and foremost, your library's name should reflect its scope. A long, descriptive name is preferable to a short one that is too generic. Some authors like to prefix their library names with "Library" to make it clearer to non-programmers that the publication is not an indicator or a strategy.
Function documentation
Programmers who cannot understand your library's functions will not use them. Your code's documentation is thus critical. Your audience will need to understand what your functions do and how to use them. Compiler directives help you structure the most important information about your library, its functions' signatures and results. Additional comments in the code of longer functions will also help other programmers understand what's going on in there. Sometimes just a few well-chosen words will help others tremendously.
The library-specific compiler directives for documentation are:
For each function, the following should be used:
These compiler directives are optional, but you should use them for every library function. When you publish your library, the text following the compiler directives will be extracted to build formatted documentation of each function, for inclusion in your publication's description.
Note that you can add additional comment lines after the `// @ returns ` directive. Those extra lines will also be extracted in your function's documentation for its publication's description.
Usage Examples
It is essential to end your library's code with well-designed usage examples. Try to maximize the quantity of functions you use in your demonstration code. If needed, show the different ways your library's key functions can be used. Comment liberally.
Note that your demonstration code can contain functions calls you would use in strategies. The broker emulator will execute orders when the library is loaded on a chart, but the chart will not display the usual markers indicating trade entries and exits.
█ PUBLISHING LIBRARIES
Private vs Public
Libraries can be published privately of publicly. Private libraries can only be used in private scripts. Public scripts must use public libraries. It is not possible to publish closed-source libraries.
Descriptions
The default function documentation text generated when you publish your library is very useful, but it is only one part of a good library publication. Your description should include more content than just the function descriptions. After validating your function documentation, write a brief explanation of your library's purpose and a general description of the type of functions it contains. Explain how your functions can be used in other Pine scripts and mention typical use cases. Include links to any useful reference material. While links are officially not allowed in descriptions, script moderators will tolerate them when their purpose is strictly educational—not to generate traffic.
The way we structure most of our library descriptions is to include the following sections:
• Overview
• Concepts
• Notes
• Functions
Note that you can include Pine code in your description by wrapping it in these tags:
Categories
As when publishing other scripts, you will also need to select the best categories to tag your publication. By choosing them wisely you make it easier for others to find your library in searches. Library categories are different from the ones displayed when publishing indicators or strategies.
█ UPDATING LIBRARIES
Like indicator and strategy publications, libraries can be updated. When you update a library, its new version number will be inserted in the update's release notes. It is important because that version number must be mentioned in the `import` statement used in scripts that use your library. Your release notes will allow users of your library to understand how each of its versions is different.
Note that library users will need to update their script's `import` statement for it to use a new version of your library. There is currently no way to make this process automatic.
█ NOTES
In order to help other programmers use their libraries, authors should be helpful and responsive to questions and requests in their publication's Comments.
While most Pine programmers will understand what your Pine library is, keep in mind that many TradingViewers do not know Pine and will not know what a library is. Please be patient when explaining to them that libraries are intended for the Pine coder community, and that they will not be useful to non-programmers.
We use the typographic guidelines and techniques documented in our How We Write and Format Script Descriptions publication to write our publication descriptions.
Follow these tips to help other Pine coders make the most out of your libraries.
Pine Libraries are open-source script publications containing functions intended for reuse by other Pine programmers. Introduced with Pine v5, they are transforming the landscape of the Pine community by making it easier for authors to share their most useful functions, and for other coders to reuse them. You will find more information on how to write and use a library in the Pine User Manual's page on libraries.
The whole point of libraries being that our community of Pine coders can use them, it follows that efforts to help others understand and use our libraries will be well spent. The following tips are good practices that will hopefully help you achieve this.
█ WRITING LIBRARIES
Scope
Clearly define your library's scope so users can quickly grasp what it's about. A library's scope may be technical analysis, array-handling, math calculations, etc. Avoid libraries containing a large number of functions, unless they cannot be divided into meaningful scopes. Single-function libraries are fine, as are ones containing only a main function and a few helper functions. You can always add functions to an existing library by updating it.
Naming
Carefully choose your library's name. It cannot contain spaces, so camelCase should be preferred. First and foremost, your library's name should reflect its scope. A long, descriptive name is preferable to a short one that is too generic. Some authors like to prefix their library names with "Library" to make it clearer to non-programmers that the publication is not an indicator or a strategy.
Function documentation
Programmers who cannot understand your library's functions will not use them. Your code's documentation is thus critical. Your audience will need to understand what your functions do and how to use them. Compiler directives help you structure the most important information about your library, its functions' signatures and results. Additional comments in the code of longer functions will also help other programmers understand what's going on in there. Sometimes just a few well-chosen words will help others tremendously.
The library-specific compiler directives for documentation are:
// @ description <Short description of your library>For each function, the following should be used:
// @ function <the function's purpose>
// @ param <one occurrence of this to describe each parameter>
// @ returns <the value(s) returned by the function, if any>These compiler directives are optional, but you should use them for every library function. When you publish your library, the text following the compiler directives will be extracted to build formatted documentation of each function, for inclusion in your publication's description.
Note that you can add additional comment lines after the `// @ returns ` directive. Those extra lines will also be extracted in your function's documentation for its publication's description.
Usage Examples
It is essential to end your library's code with well-designed usage examples. Try to maximize the quantity of functions you use in your demonstration code. If needed, show the different ways your library's key functions can be used. Comment liberally.
Note that your demonstration code can contain functions calls you would use in strategies. The broker emulator will execute orders when the library is loaded on a chart, but the chart will not display the usual markers indicating trade entries and exits.
█ PUBLISHING LIBRARIES
Private vs Public
Libraries can be published privately of publicly. Private libraries can only be used in private scripts. Public scripts must use public libraries. It is not possible to publish closed-source libraries.
Descriptions
The default function documentation text generated when you publish your library is very useful, but it is only one part of a good library publication. Your description should include more content than just the function descriptions. After validating your function documentation, write a brief explanation of your library's purpose and a general description of the type of functions it contains. Explain how your functions can be used in other Pine scripts and mention typical use cases. Include links to any useful reference material. While links are officially not allowed in descriptions, script moderators will tolerate them when their purpose is strictly educational—not to generate traffic.
The way we structure most of our library descriptions is to include the following sections:
• Overview
• Concepts
• Notes
• Functions
Note that you can include Pine code in your description by wrapping it in these tags:
[pine][/pine] Categories
As when publishing other scripts, you will also need to select the best categories to tag your publication. By choosing them wisely you make it easier for others to find your library in searches. Library categories are different from the ones displayed when publishing indicators or strategies.
█ UPDATING LIBRARIES
Like indicator and strategy publications, libraries can be updated. When you update a library, its new version number will be inserted in the update's release notes. It is important because that version number must be mentioned in the `import` statement used in scripts that use your library. Your release notes will allow users of your library to understand how each of its versions is different.
Note that library users will need to update their script's `import` statement for it to use a new version of your library. There is currently no way to make this process automatic.
█ NOTES
In order to help other programmers use their libraries, authors should be helpful and responsive to questions and requests in their publication's Comments.
While most Pine programmers will understand what your Pine library is, keep in mind that many TradingViewers do not know Pine and will not know what a library is. Please be patient when explaining to them that libraries are intended for the Pine coder community, and that they will not be useful to non-programmers.
We use the typographic guidelines and techniques documented in our How We Write and Format Script Descriptions publication to write our publication descriptions.
Tools and ideas for all Pine coders: www.pinecoders.com
Our Pine FAQ & Code: www.pinecoders.com/faq_and_code/
Pine news broadcasts: t.me/PineCodersSquawkBox or twitter.com/PineCoders
Our Pine FAQ & Code: www.pinecoders.com/faq_and_code/
Pine news broadcasts: t.me/PineCodersSquawkBox or twitter.com/PineCoders