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

[Rui Maciel]

On 04/19/2012 05:34 AM, Duncan wrote:

> 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>)

That's understandable.  The people who actually write the code tend not 
to need any explanation to tell them how thing work, how they fit in the 
grand scheme of things or why they were done the way they were.  That's 
stuff they simply know by heart.


> 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'm also not a IRC person.  It may be better to have an IRC than not to 
have one, but it is not for me.


> 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.

You are right.  I forgot there was a dev list.  Silly me.


> 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.

Yes, that's true.  Tools such as git do help in a lot more ways than 
simply managing versions of a project.  Nowadays it's almost 
inconceivable to not adopt a version control system.  With git in 
particular, the ability to stash small changes in a stack of sorts, 
which aren't tracked in the main repository, makes it even easier to 
switch to new tasks on the fly and to resume old ones as well.  Really 
nice stuff.


Rui Maciel