Structuring JavaScript libraries: documentation
Very few developer like to write documentation. The library they write is clear to them and when the hard work of programming is finished, it is difficult to decide to write the documentation. Unfortunately, without a documentation, your library is completely unusable.
The aim is not to write a long documentation, so the first step is to find what kind of documentation is the most efficient. That means: what is the shortest documentation that will be clear and precise enough.
The easiest one is to write examples. Find a set of symptomatic and concrete usages of you library. This will help users to start using it.
Later when they will need advanced features, another kind of documentation - the technical reference - is a better choice. The reference shortly describes each function, its parameters and call conditions.
Finally I suggest that you write a global description of the library, its philosophy, and general rules that have to be respected. And put it at the beginning.
All together, you have a complete documentation that is easy to write.
The best place for the technical reference is within the source code. Each time you add a new function, write a short description. Each time you modify the function, you won't forget to update the documentation.
Some would say that in JavaScript, the size of the library is critical for download time and interpretation time. Therefore they don't write comments, write compact code stripping spaces and newlines. The code becomes unreadable and difficult to maintain.
This is true but there is an easy solution. Use the JavaScript compactor and provide two versions of your library: the full documented code useful for learning and debugging, and the compacted file for production use.
You don't have any excuse not to write a good documentation. It is not that difficult and you will be the first to benefit from it when you will later reuse the library.
The aim is not to write a long documentation, so the first step is to find what kind of documentation is the most efficient. That means: what is the shortest documentation that will be clear and precise enough.
The easiest one is to write examples. Find a set of symptomatic and concrete usages of you library. This will help users to start using it.
Later when they will need advanced features, another kind of documentation - the technical reference - is a better choice. The reference shortly describes each function, its parameters and call conditions.
Finally I suggest that you write a global description of the library, its philosophy, and general rules that have to be respected. And put it at the beginning.
All together, you have a complete documentation that is easy to write.
The best place for the technical reference is within the source code. Each time you add a new function, write a short description. Each time you modify the function, you won't forget to update the documentation.
Some would say that in JavaScript, the size of the library is critical for download time and interpretation time. Therefore they don't write comments, write compact code stripping spaces and newlines. The code becomes unreadable and difficult to maintain.
This is true but there is an easy solution. Use the JavaScript compactor and provide two versions of your library: the full documented code useful for learning and debugging, and the compacted file for production use.
You don't have any excuse not to write a good documentation. It is not that difficult and you will be the first to benefit from it when you will later reuse the library.
Labels: JavaScript, Methodology
0 Comments:
Post a Comment
<$I18N$LinksToThisPost>:
Create a Link
<< Home