Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Re: documentation best practices for internal modules

by eyepopslikeamosquito (Chancellor)
on Jan 08, 2018 at 09:59 UTC ( #1206892=note: print w/replies, xml ) Need Help??


in reply to documentation best practices for internal modules

I agree with Discipulus that you should document all your modules for those that must maintain them in the future (even if that is only you).

For advice on how to document your modules, see this recent general advice on documenting Perl code.

Update: Some further commenting and documentation tips from On Coding Standards and Code Reviews:

  1. Prefer to make the code obvious.
  2. Don't belabour the obvious.
  3. Generally, comments should describe what and why, not how.
  4. Remove commented-out code, unless it helps to understand the code, then clearly mark it as such.
  5. Update comments when you change code.
  6. Include a comment block on every non-trivial method describing its purpose.
  7. Major components should have a larger comment block describing their purpose, rationale, etc.
  8. There should be a comment on any code that is likely to look wrong or confusing to the next person reading the code.
  9. Every non-local named entity (function, variable, class, macro, struct, ...) should be commented.
  10. Separate user versus maintainer documentation.
  11. CPAN Module Documentation. Tutorial and Reference; Examples and Cookbook; Maintainer; How your module is different to similar ones; Change log; Notes re portability, configuration & environment, performance, dependencies, bugs, limits, caveats, diagnostics, bug reporting.

  • Comment on Re: documentation best practices for internal modules

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1206892]
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (11)
As of 2018-07-23 14:11 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?















    Results (469 votes). Check out past polls.

    Notices?