[JDEV] Jabber/C contributing issues, was: MIU

[Mike Prince]

Documenting code is a good thing.  There are inumerable analysis
supporting this so I won't go delve into details (unless you really want
them in which I'll do it offline :)

I suggest we adopt a convention and encourage new code and rewrites to
follow it.  If this were Java, I'd say Javadoc was the way to go for at
least method level documentation.   Method level seems like a good
starting point, and it's the one I most frequesntly refer back to as I
interact with my older code and others new code.

Does someone have an example of a C coding conventions manual that they
use in their company or for personal purposes?

Thanks,

Mike

> -----Original Message-----
> From: jdev-admin at jabber.org [mailto:jdev-admin at jabber.org] On 
> Behalf Of Andrew Sayers
> Sent: Thursday, September 04, 2003 5:03 AM
> To: jdev at jabber.org
> Subject: Re: [JDEV] Jabber/C contributing issues, was: MIU
> 
> 
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> On Thu, Sep 04, 2003 at 12:42:29 +0200, maqi at jabberstudio.org wrote:
> > > I don't see how standardising the documentation format is 
> relevant 
> > > here.
> > 
> > I'm talking of code documentation, not user documentation. 
> Just like 
> > JavaDoc, Doxygen can provide a simple and handy code documentation 
> > once it is set up and the code is commented accordingly. You know 
> > Doxygen or JavaDoc?
> > 
> 
> I've just taken a look at Doxygen, and I'm not interested.  
> You still need to spend an inordinate amount of time 
> documenting your code, even if you're going to throw it away 
> in two weeks time - it's just that now the time spent 
> documenting is interspersed with time spent coding.  If you 
> like working that way, doxygen seems like a better solution 
> than spending a day writing documentation now and then, but 
> personally I couldn't work that way.
> 
> Even if you could find a way to make documentation 
> hassle-free, that's not the main point.  Explaining what a 
> function does in plain English is a hard problem which can't 
> be automated, and it takes time and skill to come up with 
> good definitions.  Normal human laziness is bound to take 
> over at some point.
> 
> > > On the other hand, implementing per-user settings really is hard 
> > > without pubsub
> > 
> > As a quick hack, one could configure the transports simply by 
> > messaging the transport contact (no pubsub required but of 
> course this 
> > can also be implemented).
> 
> Hence 'hard', not 'impossible'.  This way, you need to spam 
> all of your users on a regular basis explaining how all of 
> these functions work, find some way of detecting non-English 
> speakers, and so on.
> 
> >               And you know what?- JGF supports that. No C or C++ 
> > transport does. Strange, isn't it? ;-)
> 
> Meow!  If we're sinking to this level, I could just as easily 
> say that C programmers would rather leave this out entirely 
> (putting pressure on pubsub JEP authors, where it should be) 
> than force a kludge upon unsuspecting users, and run the risk 
> of it becoming an accepted standard.
> 
> The bottom line is that you've made one set of choices in 
> your development work, and other people have made other 
> choices.  Jabber developers aren't stupid, so their choices 
> will generally be thoughtful. Don't be so quick to assume 
> that everyone that does things a different way must be doing 
> it a worse way.
> 
> 	- Andrew
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.2.3 (GNU/Linux)
> Comment: The following is method of proving my identity.  For 
> more information, see http://www.gnupg.org.  E-mail 
> {andrew-go-away at ccl.bham.ac.uk} if you don't want this.
> 
> iD8DBQE/VyoNUjUCivGf+MsRAnhpAJ0YEEacnpeJyfezrVvzc1jzPgdyfwCgq4of
> 4Zf00LYzk/YUHxKXLxd9JUE=
> =xxdm
> -----END PGP SIGNATURE----- 
> _______________________________________________
> jdev mailing list
> jdev at jabber.org
> http://mailman.jabber.org/listinfo/jdev
>