Beefy Boxes and Bandwidth Generously Provided by pair Networks
laziness, impatience, and hubris
 
PerlMonks  

doc changes clutter vc logs (was: Re^3: Programming *is* much more than "just writing code".)

by doom (Deacon)
on May 09, 2007 at 16:34 UTC ( #614441=note: print w/replies, xml ) Need Help??


in reply to Re^2: Programming *is* much more than "just writing code".
in thread Programming *is* much more than "just writing code".

There's also the problem that purely textual changes, from typos to reattributions to rephrasing of prose can trigger RCS trails associated with the code that shouldn't be. Documentation also belongs in the RCS system, but as independant entities to the code, so that documentation changes do not affect the revision history of the code and vice versa.

This is actually a very good point (though I have to say I thought that I was the last person in the world using RCS for version control). Documentation and comment changes are more common than actual code changes (at least if you're someone like me who does re-write it to keep it up-to-date), and it might be better if those changes weren't cluttering the logs.

Damien Conway recommends against putting project documentation in a dedicated *.pod file: he argues that there's no way to be sure the *.pod will get installed correctly in some place where it can be found, but if it's inside the *.pm file, you know it's always going to be with the code.

In part, under the influence of Conway, I've been sticking to a documentation style where more tangential/higher-level material is confined to some pod at the bottom of the *.pm file (I'm a fan of "MOTIVATION" sections myself, they're often the key thing that makes clear whether you want to use a module at all). But in a multi-module project, I find I definitely have a problem with repeating myself too much, e.g. stating the project's purpose over-and-over again...

There are some clear advantages with having a project overview pod file elsewhere.

  • Comment on doc changes clutter vc logs (was: Re^3: Programming *is* much more than "just writing code".)

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (7)
As of 2020-10-27 22:00 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    My favourite web site is:












    Results (258 votes). Check out past polls.

    Notices?