On Sat, Mar 05, 2005 at 04:12:41PM -0800, Tom Jackson wrote: > I would think it is easier to simply apply a few fixes to a single file the > next time you touch it, and commit the whitespace changes first, than it > would be to only correct the code you touch.
Ok, I agree, you've convinced me. > Beyond whitespace, Jim has put in a few words about the structure of a file. Yes, did anyone stick that onto the Wiki? (Hm, actually, I don't even see where on the Wiki it should go. We need to add a new section along with the links to the API documentation?) > The result of a written standard with a conforming codebase will be cleaner > code contributed by future developers, and much simpler process of helping > new developers fix their contributions. You would be able to point to the I think this is grossly optimistic. Over time I've read a fair amount of both core AOLserver code and various modules, and hacked on some of it, and frankly, I don't remember noticing any major formatting problems. If they are present, they were never a major obstacle to my understanding of the code. So, although it is certainly a useful and laudible endeavor to clean up the formatting of the code to use only spaces (no tabs) and otherwise better conform to an AOLserver engineering manual style guide, let's be honest about the real benefits: It will make hacking on AOLserver more pleasant and a bit more productive. But that's about it. It's not going to magically attract new developers or something. In my own experience reading AOLserver code, what I'd really wished for was more comments explaining WHY something was being done, as opposed to merely what or how. (I suspect I've rambled on about this in the past...) My impression of the AOLserver code, is that as I came to understand each bit, I almost always realized that the code was actually clear, correct, and good, it just sometimes took me longer than optimal to figure that out. In particular, the use of callback-like constructs makes it harder to manually trace through the flow of control, ESPECIALLY when you don't yet have a model in your head - or in the code comments - of why and how the callbacks are arranged the way they are. (Unfortunately it's been long enough that I don't have a more concrete example handy.) That isn't really a knock against AOLserver, as I don't think I've seen ANY codebase that included enough design and internals comments to satisfy a new developer. But, it does point out one additional way we could make AOLserver codebase be made much better than average. Since the code is already quite good, it is much more amenable (than the average pile of haphazard code) to a clear description of the design intention behind it! So, as AOLserver developers maintain and renovate any code, I highly encourage you not only to fix distracting formatting issues, but to also add any additional explanatory comments which you believe useful, especially of the "why" type. My basic rule of thumb in my own programming work is, when reading code, anytime I WISH there was a comment explaining something, I stick in a TODO comment, maybe like this: TODO: Why are we fooing the bar here? Doesn't this cause a race condition with baz?? [EMAIL PROTECTED], 2005/03/06 12:22 EST Then once I actually come to understand that part of the code (hopefully soon), I replace that with something answering my original question, or pointing out why that concern does not actually apply in this case because of clever trick X, or whatever. It is no doubt possible to go overboard with that sort of commenting, but my experience is that most projects and most developers do far too little of it, not too much. -- Andrew Piskorski <[EMAIL PROTECTED]> http://www.piskorski.com/ -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
