Re: [AOLSERVER] New Config API's which document default values.

[Jim Davidson]

In a message dated 3/1/05 7:52:22 PM, [EMAIL PROTECTED] writes:

I had the timely fortune of needing to replace my crashed hard drive this
weekend and I noticed a program being installed called 'indent'. Indent is a
program which reformats the whitespace of C source code. Given a series of
switches, which can be maintained in a file, it can help developers transform
the files they are working on into a consistent style. It seems to have
enough switches to handle more than has ever been covered in either of the
written guides.

I'm sure there are downsides, but it sounds like a good way to document one
small aspect of the development standards for AOLserver.

Has anyone had good or bad experiences with this tool?

Hi,

I tried a few times to get all the switches just right for indent but failed.  Actually, I got much closer with the old BSD indent but the GNU indent was more trouble.  Would be cool if it worked.

Otherwise, I'm a big believer in a consistent style guide and I greatly appreciate when folks follow the standard -- it makes it much easier for all of us to understand new code.   The standard is a bit dated but still a good guide.  It varies from the Tcl guide a bit by choice -- I can't remember all the reasons but I think they were mostly about assuming an ANSI C compiler, e.g., eliminating needless casts from void * types.

Current variances from the standard are some times the result of folks who didn't follow the standard but more often sloppy or lazy behavior on my part, e.g., skipping a function header comment and/or form-feed formating.   My bad -- sorry about that.

In general, here are the style misses I really notice:

- Mixed up indent level stuff -- I'm ok with some mix of 8-space tabs and true spaces but I have trouble with folks using tabs only and assuming I'd just set the editor to 4 space mode.  Microsoft's Visual C interface was particularly good about getting this right so I think code I wrote there is probably closer to the goal.

- Variable name scope -- Ns_Foo for public, NsFoo for private, all other functions file-scope.  The only exceptions are ns_ function which are (mostly) wrappers of stdlib, e.g., ns_malloc and malloc -- folks shouldn't need to write anymore of those.

- Name convention for Tcl commands -- best to use NsTclFooCmd or NsTclFooObjCmd which makes it easy to search for them in the code.

- Code padding (e.g., if (a != b), not if ( a != b )) and non-compliant variable names, especially those with an underscore (e.g., my_thing_ptr instead of myThingPtr) -- I find missing these a real visual distraction.

- Comments which are not complete sentences and/or formatted properly. 

- Ordering functions in a file wrong (I often get this wrong):  It's best with init routines, public C API's, Tcl commands, aolserver-private API's, and finally static routines, in that order, e.g.:

NsInitThings
Ns_ThingCreate
Ns_ThingDo
Ns_ThingDont
NsTclThingObjCmd
NsStartThings
NsStopThings
CreateThing
DestoryThing

- Finally, and I think some will disagree, over-zeolous Tcl object command usage, in particular not using the simple and clean Tcl_AppendResult to format error messages.  I know some folks would like everything to be Tcl_Obj stuff and the new Tcl_WrongNumArgs and command switch stuff is nice but in an error condition I think stuff like this is a bit distracting:

     Tcl_SetObjResult(interp, Tcl_NewStringObj("package not known", -1));

I've found myself re-writing these sorts of things back to the old clean style:

     Tcl_AppendResult (interp, "cannot join thread ", buf, NULL);

As it's an error path, performance isn't an issue and there's not much work being done anyway.  I see the Tcl core mostly uses the old Tcl_AppendResult as well.


Otherwise, I think we've got a pretty clean code base here.

Thanks,
-Jim
2">