Re: [Pan-users] Patches with source code comments?

[Duncan]

Rui Maciel posted on Wed, 18 Apr 2012 21:18:31 +0100 as excerpted:

> I've been browsing pan's source code and I've noticed that a
> considerable number of classes don't have any comments. It might be
> helpful if some of those classes at least had a small description which
> stated its purpose and included other information, such as a brief
> description of how they were intended to be used.
> 
> So, are patches which only add this sort of comments welcomed?  If they
> are, where should they be sent?

I'm not a dev but with more devs looking at the pan code these days, I'd 
guess that would be useful.  It just wasn't Charles' style I guess, and 
based on the git-commit descriptions I've seen from HM, it's not his 
style either. (Descriptions like "adfasd" definitely make a statement 
about one's priorities! Not that I'm looking a gift horse in the mouth or 
anything, just sain'.  <g>)

FWIW if you're the IRC type (not me, give me news or lists over irc any 
day, so I definitely understand if you're not!), pan has an IRC channel 
now.  This just strikes me as a question that might be posted there 
instead of to a list, for those that are into such things.

I'd guess the dev list would be an appropriate place to send them, but do 
wait to see what the real devs say, before you get too ambitious.   In 
particular, I'm concerned that the comments might get out of sync with 
reality, if they're /too/ far down the priority list, and that helps no 
one.

Meanwhile, that brings up an observation not original to me but which 
I've noted as well:  With git's ease of branching and local commit-with-
logging, it seems that certain former code comments, etc, tend to appear 
these days as git commit descriptions, instead.  I've watched my own 
troubleshooting behavior has change, I know, such that I'm far more 
likely to run git whatchanged and search on some particular filename or 
keyword, than to go grepping the code itself for comments, these days.  
The combination of the diff and the commit description that goes with it 
says a lot more than either one by itself, and for devs that use such 
descriptions well, at least, it works better than code comments, since 
the description is locked to the code change and thus can't go stale.

Of course, that DOES mean that for devs wanting to grok and change the 
code, using the git version is nearly essential now.  It's no longer 
sufficient to just grab the latest tarball and study the code in it.

I've noted various commentary with similar observations about changelogs, 
etc.  While a cursory user-level changelog/news is still expected in the 
announcement and often shipped in the tarball as well, more and more 
projects are dropping the higher level of detail they used to provide in 
such changelogs, expecting anyone interested at /that/ level of detail to 
be using git, and simply doing a git whatchanged.  This has quite the 
implications for a distro package maintainer's workflow, etc, since now, 
instead of doing the tarball thing, they're doing a git pull and a 
checkout of the desired tag, for their build.  That makes it rather 
easier to search and cherrypick or revert individual commits, too, doing 
it all on the local git-cloned copy, instead of grabbing the patches from 
bugs or git-web, etc.

Actually, some projects are taking it even farther than that, with 
individual distros maintaining their own upstream branches as well, and 
package maintainers simply tagging their own versions complete with 
patches, cherrypicks and reversions, on upstream branches maintained in 
the same repo but separate from upstream's primary branch.

The implications of this really end up being quite enormous, actually.  
I've seen predictions that in a few years, the git revolution will be 
ranked right up there with the internet revolution, in terms of the 
effect it had on the FLOSS community and software.  If the internet 
revolution changed cathedral style FLOSS development to bazaar as is 
famously argued and widely accepted, what metaphor will be appropriate 
for the git revolution?

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman