Beefy Boxes and Bandwidth Generously Provided by pair Networks
Problems? Is your data what you think it is?
 
PerlMonks  

Re^2: Deriving meaning from source code, some code is self documenting

by submersible_toaster (Chaplain)
on Dec 11, 2008 at 01:55 UTC ( #729581=note: print w/replies, xml ) Need Help??


in reply to Re: Deriving meaning from source code, some code is self documenting
in thread Deriving meaning from source code, some code is self documenting

There is a certain level of 'boilerplate' information (let's not call it documentation) that other more strictly parsable languages tend to provide as part of code documentation. The approach described is without a doubt driven by analyze bad code , for certain values of bad.

In general a list of methods by itself is not documentation, neither is an inheritance tree

In general - would you expect an author to document , in POD linked references to parent classes / dependencies in a helpful =head1 INHERITS or =head1 DEPENDS ON section? This is the sort of boilerplate that is a) manual and tedious , b) comes for free with many other languages, c) prone to outdated-ness(see a)

Generate documentation - no. Enhance existing documentation - yes. Soften the blow in the absence of ANY documentation - maybe. Provide hints to author/maintainer about the nature of a piece of code versus the nature of the associated documentation - possibly.

The zero day script simply tacked it's conclusions (as pod) onto whatever pod already existed before passing that to a final formatter, in this case HTML. I wouldn't suggest baking it's output back into the original code anymore than I would suggest perlcritic users insert comments in their code for every critic message.

Perhaps consider Macropod to be a step towards a Pod::Critic which in addition to nagging about common pod formatting mistakes, would suggest that you only appear to have pod sections for functions 'foo' and 'bar' , but are exporting '&zebra' which has no associated documentation.


I can't believe it's not psellchecked

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://729581]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others romping around the Monastery: (5)
As of 2019-06-20 21:30 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Is there a future for codeless software?



    Results (91 votes). Check out past polls.

    Notices?