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 On Monday, 9 February 2015 23:26:12 UTC+1, Mad Frode wrote: > > 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 <https://github.com/ck86/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 > -- Job board: http://jobs.nodejs.org/ New group rules: https://gist.github.com/othiym23/9886289#file-moderation-policy-md Old group rules: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines --- You received this message because you are subscribed to the Google Groups "nodejs" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/nodejs/388adedf-9361-4758-a1d1-63f9a2294b04%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
