Question on comment-documentation for a npm package

[Mad Frode]

I am trying to figure out how and how much I should comment my node module. To learn from others, I took a look at a npm-package, main-bower-files.

I see that package_collection.js and package.js are well documented in the style that I see on usejsdoc.org. But the main file, index.js is not commented at all. The first files are objects with constructors, methods and such, but the main file index.js has not, but it has a couple of paramenters, Is it only modules with objects with methods and such API-related stuff that should get such comment-documentation? And/or is it perhaps because the the README-file has a description on how to use the main file (index.js) then there is no need to make any comment-documentation in the index.js?

Any thoughts would be much appreciated!

Frode

[David Finnie]

Hi Frode,

Being reasonably new to the whole Node.js community (I have just implemented Node.js on a new platform - HP NonStop systems), I am rather dismayed at the lack of documentation in some areas (while I'm happy to say that some areas are documented well). It is very hard to document *too* much, so I would say "go nuts!!!". Maybe you could set a new standard :-) If you could also include lots of documentation in the code itself, that is also a huge help to any developers that might work on your code in the future (including yourself in 2 or 3 years time!).

My 2c worth :-)

Dave

[Floby]

Hello,

While some authors see the need to comment your code as a smell [1] I reckon not everyone can write readable and understandable code.

The general recommendation I'd make is to 

- Write a README which covers the basic usage of your module, leave edge cases elsewhere

- Write a developer README, which covers how to run tests and how the module generally works

- Write tests with meaningful names

- Write an index.js file that gives the reader enough pointers to find whatever he or she is looking for

- Everytime you feel the need to write a comment, rewrite your code instead

[1] http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882