Re: GNUstep Coding Standard Additions
This is a repost to the gnu.gnustep.discuss newsgroup, because gnu.org is dropping my mailing list postings on the floor with an Invalid address in message header error. Alex Perez wrote: Richard Frith-Macdonald wrote: [snip] So, for each class/method, we need to know which version of MacOS-X it was introduced at, or whether it is from the original OpenStep spec. I think, for simplicity, we might categorize methods/classes introduced by NeXT/OPENSTEP after the OpenStep specification was published as being 'MacOS-X' methods. Yes, this is essentially what Sheldon and I also thought would be the right thing to do, so it seems we're all in agreement on this point. These statements are too simplistic; OPENSTEP did make extensions to OpenStep, but also added things to (and removed things, like NSHelpPanel from) OpenStep. The AppKit and Foundation release notes for 4.2, as well as the 4.2 docs, tell which is which. The proprietary things that NeXT added, like NSFileManager etc. could be considered Mac OS X stuff. But not the things that are part of the OpenStep specifications as amended by OPENSTEP 4.x. [snip] -- | Jeff Teunissen -=- Pres., Dusk To Dawn Computing -=- deek @ d2dc.net | GPG: 1024D/9840105A 7102 808A 7733 C2F3 097B 161B 9222 DAB8 9840 105A | Core developer, The QuakeForge Projecthttp://www.quakeforge.net/ | Specializing in Debian GNU/Linux http://www.d2dc.net/~deek/ ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-05-08 22:14:51 +0100 Alex Perez [EMAIL PROTECTED] wrote: So what do you advocate for the parts of the API which were introduced after OpenStep, but before MacOS-X, and the parts of the API which were in OpenStep but were removed before MacOS-X was released? It should be obvious, but I can spell it out if it's really necessary. If something that did not exist in the OpenStep spec first appeared in OS X 10.0, which was the first *RELEASED* product to contain the API addition or modification, it will be marked as being introduced in OS X 10.0, which is absolutely correct, since it was the first released OS to contain the changes. If something was removed before OS X 10.0 was released, for instance, it is not a part of OS X 10.0, and would either be marked as deprecated or removed as of OS X 10.0 in our documentation. This seems plainly obvious... I'm afraid I've been going through emails in strict order ... so I think I've already adressed this point ... basically you can orf course do that, but saying that nothing was released between the OpenStep specification and the release of MacOS-X is to ignore a few years of NeXT's development of the OPENSTEP operating system. I think there were releases of 4.0, 4.1, and 4.2 ... but I'm not an OPENSTEP user, and I don't know if nthere were other releases or exacttly which releases introduced/removed which features in the API. I plan to document it in the same place where the method documentation is, for the sake of consistency, which is not in the headers. Except where it IS in the headers... You're kidding, right? Some GNUstep classes have the documentation in the headers, and some have it in the source? that's so utterly wrong and needs to be fixed, if so. Again, I think I addressed this in an earlier reply because I've been going through emails in order ... to clarify. All classes have documentation generated from the .h files. Most also get documentation from the .m files. For technical reasons, using the .h files is mandatory, using the .m files is optional (some parts of the API, such as macros, appear only in the .h files ... because that's just the way C/Objective-C works). I am not at all convinced that implementing these over-the-top and IMHO unnecessary/not-very-useful macros are worth my time. If you really think they are of value to you, I would of course encourage you or anyone else who needs this level of functionality to implement this, but I myself am not willing to invest the needed time into this specific aspect of things. I am quite happy to implement this simple macro ... I was suggesting that you use it to produce the documentation markup, as it would be (as far as I can see) the simplest/quickest way of producing the markup. I don't really see how, at all. 1. using a #if macro #endif sequence you can mark a whole chunk of the API in one go, rather than having to markup each API element separately (though if you want to mark each method separately, you still can). A quick fgrep of the base library headers shows under 100 occurrances of the 'STRICT_' prefix which currently generates the information for OpenStep/MacOS-X/GNUstep discrimination in the documentation. Contrast this with the huge number of classes, methods, functions, macros, types, and constants in the base API, and you can see how efficient it is. 2. the macro lets people compile with a particular api version by defining a single preprocessor constant, rather than as suggested by sheldon, us having to write a new tool to get version information from the documentation and examine their code. Nothing wrong with having such a tool ... but we don't yet, and it would not be an extra stage that users would have to run their code through (and unless it was really, really clever, it would be less good at pointing out where in their code the problems lie). ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Alex Perez wrote: I think whether or not a class was introduced in OPENSTEP 4.0, 4.1, or 4.2, at this point, is completely irrelevant, and I personally am not going to research this. Besides, we work off the OpenStep specification, not anything else, when it comes to the original API documentation. For the newer apple-added stuff, we just need to note which version of OS X the API was introduced, as well as which version of of GNUstep it was implemented in. Hello Alex, I appreciate that you are not be interested in doing this research and that you won't volunteer to add this documentation, this is absolutely reasonable. But in the case of corporate installations that are still running large applications based on these versions, it can be very important during the migration phase to be able to write code that works with both GNUstep and the old API. Please don't declare it as irrelevant just because you don't have a use for it. Personally I only have use for WebObjects 4.5 (which added some tweaks which are not strictly OPENSTEP 4.2, but using OPENSTEP 4.2 as a common ground has been very useful). But I can very well imagine that there are good uses for other OPENSTEP API. Now I'm not saying that I think it is our duty to supply all this versioning mechanism, but that if easily done and maintained, that such a framework that allows contributors to support the older API selection would be very useful. Cheers, David ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
I think we are agreed that we want to categorise a method/class by the version where it was introduced, and the version where it was removed (NeXT/Apple have removed some things from their APIs) This sounds like a good plan. Just to be clear, deprecation does NOT count as removal, right? I would say the headers should be rearranged so that methods appear in order of the version in which they first appeared, and alphabetically within a version. That way, adding/findng methods for a particular version range is trivial. Currently most of the headers are not alphabetized, but have methods organized by functional area. E.g, in NSDate: // Adding and getting intervals - (id) addTimeInterval: (NSTimeInterval)seconds; - (NSTimeInterval) timeIntervalSince1970; - (NSTimeInterval) timeIntervalSinceDate: (NSDate*)otherDate; ... // Comparing dates - (NSComparisonResult) compare: (NSDate*)otherDate; - (NSDate*) earlierDate: (NSDate*)otherDate; I'm not wedded to this, but it's been around a long time and people are used to it. Rather than changing it everywhere, how about just alphabetizing / sorting the additions and changes? #else if OSVERSION(4.2, 10.3) // Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in How important is this tracking of OpenStep spec vs. OpenStep 4.2 (and 4.1, etc.)? Do we even have online reference documentation for this? It seems like we have just been marking OpenStep in the API so far without distinguishing versions and no complaints. Also, I'm worried that OSVERSION will be confusing, particularly when looking at code sitting on an Apple system. How about STEP_VERSION, API_VERSION, OS_API_VERSION, STEP_RELEASE, or ... ? ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-05-08 14:17:27 +0100 Adrian Robert [EMAIL PROTECTED] wrote: I think we are agreed that we want to categorise a method/class by the version where it was introduced, and the version where it was removed (NeXT/Apple have removed some things from their APIs) This sounds like a good plan. Just to be clear, deprecation does NOT count as removal, right? Correct ... deprecation and removal are different. I would say the headers should be rearranged so that methods appear in order of the version in which they first appeared, and alphabetically within a version. That way, adding/findng methods for a particular version range is trivial. Currently most of the headers are not alphabetized, but have methods organized by functional area. E.g, in NSDate: Not sure about 'most' ... it's a currently a mix, but I don't know the proportions. I'm not wedded to this, but it's been around a long time and people are used to it. Rather than changing it everywhere, how about just alphabetizing / sorting the additions and changes? Sounds OK ... I just think it's easier and more useful to organize by version, and straightforward to alphabetize within groups. Ordering by functional areras is very vague ... it's quite subjective what you consider to be a functional area (and we should try not to copy Apple as a general principle). I don't much care though. #else if OSVERSION(4.2, 10.3) // Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in How important is this tracking of OpenStep spec vs. OpenStep 4.2 (and 4.1, etc.)? Do we even have online reference documentation for this? It seems like we have just been marking OpenStep in the API so far without distinguishing versions and no complaints. I'm not sure about OPENSTEP versions, but we certainly discriminate between OpenStep (the specification, which we certainly do have online documentation for) and later APIs. There are certainly a few APIs that were added/removed between OpenStep and MacOS-X, so logically, we need to give them addition/removal versions other than 0.0 or 10.0 Personally, we could call them all 4.0 for all I care, but I imagine some people will want this to be correct. Also, I'm worried that OSVERSION will be confusing, particularly when looking at code sitting on an Apple system. How about STEP_VERSION, API_VERSION, OS_API_VERSION, STEP_RELEASE, or ... ? I have no opinion on the exact naming we use ... I just suggested the first name that came into my head. If Alex is in a hurry to categorise, he oculd use any name and we could do a global search/replace to change it later. For convenience. it should be a short but unique name which is fairly self-explanatory. ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote: On 2005-05-07 08:59:45 +0100 Alex Perez [EMAIL PROTECTED] wrote: Sheldon, Richard, Adam, et. al: Alex Perez wrote: Sheldon Gill wrote: I'd be very happy to create a write up for you and help/mentor the process. I may be able to assist with a few tools as well. The sooner this is done, and agreed to by most, the sooner I can get started. My apologies for replying to my own post, but I'd like to push this forward. Can we all please go over roughly what we want to have me do, what exactly we want documented, and how we want to document it, so I can get cookin'? I'd like to get going on this tomorrow, although I realize that may not happen. I don't think we have complete agreement yet ... but I think we *are* agreed that knowing the MacOS-X release version for each class/method is good. I'm less sure about the GNUstep release version... I don't think this has been discussed thoroughly, and I worry that tracking two separate sets of versioning might be too much of an overhead. Certainly it would get confusing if you put in both MacOS-X and GNUstep version information for the same method ... so probably GNUstep versioning information should be restricted to those classes/methods which are GNUstep additions (not in MacOS-X/OpenStep). I agree with this, with one exception. If a class or method came from OS X, we should note when it was implemented in GNUstep, (which *release* version of base or GUI), don't you think? I think that's going to be important, going forward. So, for each class/method, we need to know which version of MacOS-X it was introduced at, or whether it is from the original OpenStep spec. I think, for simplicity, we might categorize methods/classes introduced by NeXT/OPENSTEP after the OpenStep specification was published as being 'MacOS-X' methods. Yes, this is essentially what Sheldon and I also thought would be the right thing to do, so it seems we're all in agreement on this point. That is to say, we have three categories - 1. Things from the original openstep implementation 2. GNUstep specific additions 3. NeXT/Apple additions However, for simplification, we can treat the opriginal OpenStep spec as MacOS-X version 0.0 and the NeXT releases of the OPENSTEP system as being versions 4.0, 4.1, 4.2 (can't remember if OPENSTEP ever got beyond 4.2). I think whether or not a class was introduced in OPENSTEP 4.0, 4.1, or 4.2, at this point, is completely irrelevant, and I personally am not going to research this. Besides, we work off the OpenStep specification, not anything else, when it comes to the original API documentation. For the newer apple-added stuff, we just need to note which version of OS X the API was introduced, as well as which version of of GNUstep it was implemented in. I think we are agreed that we want to categorise a method/class by the version where it was introduced, and the version where it was removed (NeXT/Apple have removed some things from their APIs) Most of what they have removed they have actually deprecated, but yes, they have removed *some* stuff, and I plan to note it. Now, I guess you could just build up a table of this information, or you could edit the headers... I plan to document it in the same place where the method documentation is, for the sake of consistency, which is not in the headers. I would say the headers should be rearranged so that methods appear in order of the version in which they first appeared, and alphabetically within a version. That way, adding/findng methods for a particular version range is trivial. Not a bad idea, but I'm not sure if I'm willing to do this just yet. We could define a standard macro to handle versioning, taking two arguments indicating the version at which the method was introduced, and the version at which it was removed. eg. #if OSVERSION(0, 0) // OpenStep methods which were never implemented in OPENSTEP or MacOS-X #else if OSVERSION(0, 10.3) // OpenStep methods which were removed in MacOS-X 10.3 #else if OSVERSION(4.2, 10.3) // Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in MacOS-X 10.3 #else if OSVERSION(10.0, 10.4) // MacOS-X methods introduced in MacOS-X 10.0 and removed in 10.4 #else if OSVERSION(10.0, FUTURE) // MacOS-X methods introduced in MacOS-X 10.0 and still present #else if GSVERSION(0, FUTURE) // GNUstep additions #endif The GSVERSION macro might handle versioning of GNUstep specific additions, separately from the OSVERSION macro Defining the STRICT_OPENSTEP macro would select methods where the starting version is 0.0. Defining STRICT_MACOS_X would select methods where the ending version 10.0 Defining a MACOS_VERSION would select methods where start version = MACOS_VERSION and end version MACOS_VERSION I am not at all convinced that implementing these over-the-top and IMHO unnecessary/not-very-useful macros are worth my time. If you really think they are of value to you, I would of
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote: On 2005-05-08 14:17:27 +0100 Adrian Robert [EMAIL PROTECTED] wrote: I think we are agreed that we want to categorise a method/class by the version where it was introduced, and the version where it was removed (NeXT/Apple have removed some things from their APIs) This sounds like a good plan. Just to be clear, deprecation does NOT count as removal, right? Correct ... deprecation and removal are different. I would say the headers should be rearranged so that methods appear in order of the version in which they first appeared, and alphabetically within a version. That way, adding/findng methods for a particular version range is trivial. Currently most of the headers are not alphabetized, but have methods organized by functional area. E.g, in NSDate: Not sure about 'most' ... it's a currently a mix, but I don't know the proportions. I'm not wedded to this, but it's been around a long time and people are used to it. Rather than changing it everywhere, how about just alphabetizing / sorting the additions and changes? Sounds OK ... I just think it's easier and more useful to organize by version, and straightforward to alphabetize within groups. Ordering by functional areras is very vague ... it's quite subjective what you consider to be a functional area (and we should try not to copy Apple as a general principle). I don't much care though. #else if OSVERSION(4.2, 10.3) // Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in How important is this tracking of OpenStep spec vs. OpenStep 4.2 (and 4.1, etc.)? Do we even have online reference documentation for this? It seems like we have just been marking OpenStep in the API so far without distinguishing versions and no complaints. I'm not sure about OPENSTEP versions, but we certainly discriminate between OpenStep (the specification, which we certainly do have online documentation for) and later APIs. There are certainly a few APIs that were added/removed between OpenStep and MacOS-X, so logically, we need to give them addition/removal versions other than 0.0 or 10.0 Personally, we could call them all 4.0 for all I care, but I imagine some people will want this to be correct. None of these intermediate parts were ever officially released. Good documentation on when, exactly, something was added to Rhapsody, for instance, is completely lacking because of this, and I only think we should be dealing with *released* API changes, in which case 10.0 would be the first MacOS X version which contained the new API additions. Also, I'm worried that OSVERSION will be confusing, particularly when looking at code sitting on an Apple system. How about STEP_VERSION, API_VERSION, OS_API_VERSION, STEP_RELEASE, or ... ? I have no opinion on the exact naming we use ... I just suggested the first name that came into my head. If Alex is in a hurry to categorise, he oculd use any name and we could do a global search/replace to change it later. For convenience. it should be a short but unique name which is fairly self-explanatory. See my two previous e-mails on this issue. Cheers, Alex Perez ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Adrian Robert wrote: I think we are agreed that we want to categorise a method/class by the version where it was introduced, and the version where it was removed (NeXT/Apple have removed some things from their APIs) This sounds like a good plan. Just to be clear, deprecation does NOT count as removal, right? No, deprecation counts as deprecation, and should be noted as such. :) I would say the headers should be rearranged so that methods appear in order of the version in which they first appeared, and alphabetically within a version. That way, adding/findng methods for a particular version range is trivial. Currently most of the headers are not alphabetized, but have methods organized by functional area. E.g, in NSDate: // Adding and getting intervals - (id) addTimeInterval: (NSTimeInterval)seconds; - (NSTimeInterval) timeIntervalSince1970; - (NSTimeInterval) timeIntervalSinceDate: (NSDate*)otherDate; ... // Comparing dates - (NSComparisonResult) compare: (NSDate*)otherDate; - (NSDate*) earlierDate: (NSDate*)otherDate; I'm not wedded to this, but it's been around a long time and people are used to it. Rather than changing it everywhere, how about just alphabetizing / sorting the additions and changes? Well, as I just wrote in another e-mail, it's not something I am willing to do, so unless someone else is going to, it ain't gonna happen ;-) #else if OSVERSION(4.2, 10.3) // Methods not in OpenStep, but present in OPENSTEP 4.2, then removed in How important is this tracking of OpenStep spec vs. OpenStep 4.2 (and 4.1, etc.)? Do we even have online reference documentation for this? It seems like we have just been marking OpenStep in the API so far without distinguishing versions and no complaints. Completely not important. It might have been 10 years ago. I will not be tracking this either, as stated in the other e-mail. Also, I'm worried that OSVERSION will be confusing, particularly when looking at code sitting on an Apple system. How about STEP_VERSION, API_VERSION, OS_API_VERSION, STEP_RELEASE, or ... ? Nor will I be implementing the macros (yet), so you guys can discuss this into the ground while I go get some documentation work done :) My personal opinion on the matter is that the OSVERSION macro is utterly unnecessary, and should absolutely not be added. Cheers, Alex Perez ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote: On 2005-05-08 19:26:12 +0100 Alex Perez [EMAIL PROTECTED] wrote: However, for simplification, we can treat the opriginal OpenStep spec as MacOS-X version 0.0 and the NeXT releases of the OPENSTEP system as being versions 4.0, 4.1, 4.2 (can't remember if OPENSTEP ever got beyond 4.2). I think whether or not a class was introduced in OPENSTEP 4.0, 4.1, or 4.2, at this point, is completely irrelevant, and I personally am not going to research this. Besides, we work off the OpenStep specification, not anything else, when it comes to the original API documentation. For the newer apple-added stuff, we just need to note which version of OS X the API was introduced, as well as which version of of GNUstep it was implemented in. So what do you advocate for the parts of the API which were introduced after OpenStep, but before MacOS-X, and the parts of the API which were in OpenStep but were removed before MacOS-X was released? It should be obvious, but I can spell it out if it's really necessary. If something that did not exist in the OpenStep spec first appeared in OS X 10.0, which was the first *RELEASED* product to contain the API addition or modification, it will be marked as being introduced in OS X 10.0, which is absolutely correct, since it was the first released OS to contain the changes. If something was removed before OS X 10.0 was released, for instance, it is not a part of OS X 10.0, and would either be marked as deprecated or removed as of OS X 10.0 in our documentation. This seems plainly obvious... Now, I guess you could just build up a table of this information, or you could edit the headers... I plan to document it in the same place where the method documentation is, for the sake of consistency, which is not in the headers. Except where it IS in the headers... You're kidding, right? Some GNUstep classes have the documentation in the headers, and some have it in the source? that's so utterly wrong and needs to be fixed, if so. We could define a standard macro to handle versioning, taking two arguments indicating the version at which the method was introduced, and the version at which it was removed. I am not at all convinced that implementing these over-the-top and IMHO unnecessary/not-very-useful macros are worth my time. If you really think they are of value to you, I would of course encourage you or anyone else who needs this level of functionality to implement this, but I myself am not willing to invest the needed time into this specific aspect of things. I am quite happy to implement this simple macro ... I was suggesting that you use it to produce the documentation markup, as it would be (as far as I can see) the simplest/quickest way of producing the markup. I don't really see how, at all. Alex ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-05-08 19:32:28 +0100 Alex Perez [EMAIL PROTECTED] wrote: I'm not sure about OPENSTEP versions, but we certainly discriminate between OpenStep (the specification, which we certainly do have online documentation for) and later APIs. There are certainly a few APIs that were added/removed between OpenStep and MacOS-X, so logically, we need to give them addition/removal versions other than 0.0 or 10.0 Personally, we could call them all 4.0 for all I care, but I imagine some people will want this to be correct. None of these intermediate parts were ever officially released. Good documentation on when, exactly, something was added to Rhapsody, for instance, is completely lacking because of this, and I only think we should be dealing with *released* API changes, in which case 10.0 would be the first MacOS X version which contained the new API additions. I'm not sure what you mean by 'officially released' ... I know that NeXT released multiple versions of OPENSTEP, and I see no reason why these should have a different status as 'official releases' from the versions of MacOS-X we have seen released. I know that some classes which were present in the OpenStep specification were dropped from OPENSTEP releases (eg NSByteStore). I know that some classes which were not present in OpenStep appeared in some of the OPENSTEP releases (eg NSFileManager) I guess you can ignore this history and say that all the changes took place in MacOS-X ... but I think to do so would be saving up trouble for when OPENSTEP users, historians, and pedants complain. ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-05-03 03:09:02 +0100 Sheldon Gill [EMAIL PROTECTED] wrote: Richard Frith-Macdonald wrote: Secondly, I'd like the docs to clearly state the source for functions/methods as OpenStep, MacOS (differentiate puma, jaguar, panther and tiger) or GS (version). The current documentation does that for Openstep/MacOS/GNUstep ... so extending the mechanism to differentiate between individual MacOS and GNUstep releases should be fairly simple ... it's just that it would take a lot of time to review methods to find which release each belongs to. I guess we could extend the existing STRICT_OPENSTEP/STRICT_MACOS_X classification, but I think it might be better to add gnustep and openstep versioning as separate defines or as markup in the comments. I was thinking purely of the documentation, not source modifications. I was envisaging an improvement to the markup so functions/methods could be easily categorised as I indicated. The autogsdoc program generates the markup from the headers ... so source modifications go hand in hand with markup changes. The advantage of using defines and using #ifdef/#ifndef/#if defined() is that people can then easily check that their code does not use features which are not present in a particular version, however it's a bit more cumbersome to deal with. I understand the intended purpose of this but I don't think it delivers value. At the moment the classification of STRICT_MACOS_X is too broad to be of any real benefit. Imo STRICT_OPENSTEP no longer provides any value at all. It certainly did in the earlier days of the project but I think its time is well and truly passed. I have no use for those defines either ... but they were put in because others *do* have a use for them and asked for them ... even the old openstep compatibility! It's a big mistake to assume that, just because we have no use for a feature, the feature should be removed. Adding a more fine grained control of the MACOS-X information would obviously be an improvement. I would prefer to continue with making sure that the defines in the header files mark the classification of each method accurately, and extend autogsdoc to generate such a table using that information... then the table can be kept in sync with the text of the documentation easily. As I said previously, I don't think the defines provide enough value for the effort to maintain it. Dropping them would allow the headers to be re-organised along functional lines and I think that is more valuable to the project than the conditional header route. Two things ... 1. other people wanted the defines, and we have no evidence that they are no longer wanted. 2. headers should *not* be organised on functional lines ... Apple do that, and we try hard to make headers as dissimilar to Apples as reasonably possible, to avoid any possibly accusations of copyright infringement. This is also why we try to pick different formal names for the method arguments in the header files, and use whitespace differently from apple. Additionally, consider this: Assume the documentation system has been improved to provide a reasonably fine grained classification. Hence the gsdoc standards tag generated now reflects this. When a new API is added, the documentation (right above the implementation ;) is tagged appropriately. Easy. Using #defines in the header achieves the same effect. In fact, if we order the headers by API version, we can make it even easier, since inserting a new method into the correct location in the header gets it tagged in the documentation, without us having to write a single additional character. This is reflected in the gsdoc output. It'd be quite easy for someone to write a small tool to parse the XML output to pick up on the tags needed to automatically generate the complete table. It'd also be easy to create tool that takes that table and scans for symbols which shouldn't be used. That would provide a *much* better basis for portability checks and assistance than #ifdef in the headers. It wouldn't ... because, since the documentation is generated from the headers, any possible advantage you can imagine which is based on parsing the xml automatically applies to the ifdef in the header solution too. Using the defines in the headers has two advantages over adding explicit markup in the comments - 1. Less work to do generating the markup. 2. Compile time compatibility checking is available. So I agree with the idea of the more finer grained versioning ... but it needs to be done as an extension improvement to the current state of things rather than losing functionality by requiring explicit markup in the comments. ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote: Secondly, I'd like the docs to clearly state the source for functions/methods as OpenStep, MacOS (differentiate puma, jaguar, panther and tiger) or GS (version). The current documentation does that for Openstep/MacOS/GNUstep ... so extending the mechanism to differentiate between individual MacOS and GNUstep releases should be fairly simple ... it's just that it would take a lot of time to review methods to find which release each belongs to. I guess we could extend the existing STRICT_OPENSTEP/STRICT_MACOS_X classification, but I think it might be better to add gnustep and openstep versioning as separate defines or as markup in the comments. I was thinking purely of the documentation, not source modifications. I was envisaging an improvement to the markup so functions/methods could be easily categorised as I indicated. The autogsdoc program generates the markup from the headers ... so source modifications go hand in hand with markup changes. In my mind there is a substantial difference between the concepts of source modifications and additional documentation mark ups. Particularly, if the person looking at making the changes is reasonably confident in so far as the documentation is concerned but not coding. Making a mistake in the doc markup isn't going to be a big deal. Breaking compilation because you've got the conditionals wrong is. The advantage of using defines and using #ifdef/#ifndef/#if defined() is that people can then easily check that their code does not use features which are not present in a particular version, however it's a bit more cumbersome to deal with. I understand the intended purpose of this but I don't think it delivers value. At the moment the classification of STRICT_MACOS_X is too broad to be of any real benefit. Imo STRICT_OPENSTEP no longer provides any value at all. It certainly did in the earlier days of the project but I think its time is well and truly passed. I have no use for those defines either ... but they were put in because others *do* have a use for them and asked for them ... even the old openstep compatibility! I know others have used them in the past. I'm not sure who is using them at all today. Besides which, the question I was raising is value. What is the real value in keeping them? What is the value in getting rid of them? What is the effort in properly maintaining them. I see the choice: a) Better, more complete documentation which is readily accessible b) Trawl your way through conditionals in the headers and work it out If we're to make it easier and better I think (a) has far more value to the project than (b). It's a big mistake to assume that, just because we have no use for a feature, the feature should be removed. Why? If *we* have no use for a feature, why shouldn't it be removed? Should all features be retained forever? I would prefer to continue with making sure that the defines in the header files mark the classification of each method accurately, and extend autogsdoc to generate such a table using that information... then the table can be kept in sync with the text of the documentation easily. As I said previously, I don't think the defines provide enough value for the effort to maintain it. Dropping them would allow the headers to be re-organised along functional lines and I think that is more valuable to the project than the conditional header route. Two things ... 1. other people wanted the defines, and we have no evidence that they are no longer wanted. Nor do we have evidence that they do. I'm not sure how much other people are using the project these days, either. 2. headers should *not* be organised on functional lines ... Apple do that, and we try hard to make headers as dissimilar to Apples as reasonably possible, to avoid any possibly accusations of copyright infringement. This is also why we try to pick different formal names for the method arguments in the header files, and use whitespace differently from apple. Benefit vs cost. I don't think Apple is going to come after us just because we re-arrange the headers. We use while space differently. We use different formal names. We have different implementations and documentation. We even put some methods/functions in different header to Apple. These things are far more important. API compatibility doesn't constitute copyright infringement. Even in the US. Additionally, consider this: Assume the documentation system has been improved to provide a reasonably fine grained classification. Hence the gsdoc standards tag generated now reflects this. When a new API is added, the documentation (right above the implementation ;) is tagged appropriately. Easy. Using #defines in the header achieves the same effect. From your perspective perhaps. Certainly not from mine. The level and accessibility of documentation is very different between the two in my view. The Usefulness factor is IMO much greater
Re: GNUstep Coding Standard Additions
Fine. We're mostly agreed. I'm just really against single letter identifiers for the non-mathematical case. Always. That was really the point that I was making, even if I wasn't so clear about it. Single letter identifiers can make sense for the non-mathematical case. I think on this there is no agreement and different developers have different tastes / habits. I don't see why we should force developers to follow one way of coding if there is no agreement. ;-) As I said, both are used internally and I think that situation is bad. Thus, we should pick the one true style for this as part of the canon. Can we agree that *one* method is better than two? Yes ... but I don't think it's sufficiently better that one should be insisted upon when people contribute. I think that the NeXT style is overwhelmingly more common, so I prefer it, and it's no real trouble to convert gnu-style function names to NeXT style ones. Ahah! Take a look at what you wrote. I take it that you're saying that the NeXT style is the standard and gnu_style_function names should be changed to comply. Isn't that so? Well you seem to ignore why we have this mixture of different styles. The OpenStep API uses a certain style (like NSDrawRect). The GNU Objective-C runtime API though uses a different style (like objc_free). We are in the middle between the two. ;-) Moreover, we are supposed to be following the GNU Coding Standards, which require GNU C style to be used for all C code (it doesn't talk about ObjC code though). Eg, think of public stuff we add: if we're adding something which looks like an ObjC runtime extension, it becomes natural to use the GNU ObjC style; if we're adding something that looks like an OpenStep extension it becomes natural to use the OpenStep style. Internal implementation details are a bit in the middle of those two cases. If you're doing mostly C stuff, it becomes natural to use GNU C style conventions; if you're doing mostly ObjC stuff, it becomes natural to use OpenStep ObjC conventions. An idea is using OpenStep ObjC conventions for all ObjC class/method/protocol/object names and for public functions meant to be extensions of OpenStep (except when it has to do with the runtime), and GNU C/ObjC conventions for all function/C variables. I believe in the mind of some developers this is what we are already doing ;-) Anyway, the essential point is that there is a reason why we have two styles in use, and you can't ignore it ... ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote:
So your recommendation is
static NSString *
BundleObjectName(NSString *path, NSString* executable)
over
static NSString *
bundle_object_name(NSString *path, NSString* executable)
in this module private case?
Actually, my recommendation is to not force people to a single style
when contributing. However, our standard style would be without
underscores (ie the one used generally because it *has* to be used for
the public api). I think function names usually have a lowercase
initial letter if they don't have the NS or GS prefix though.
You see? You're not certain about the initial letter. Someone who has
been contributing substantial amounts of code for years.
This is a big part of the issues I'm trying to raise and address. You
say our standard style but my point is that both styles are used and
there is nothing in the 'Standard'.
You note its generally used. Not universally used. The reason being
there are choices here. I'm advocated establishing clear rules for the
'Standard' for everyone to follow.
That said, I am *not* advocating using those rules as a strict patch
filter. I'm not recommending we force contributors to comply. I am
rather advocating defining rules for the 'Standard' which maintainers
will comply with.
I'm not saying we then try an force maintainers to go to the source and
immediately revise everything to comply, either. Once everyone
maintaining knows the rules the code base will move towards compliance.
If someone gets all enthusiastic thats fine. Otherwise it'll take some
time. I'm fine with that, too.
I think we should also be clear that dictionary or dict is
preferred over d. Except for mathematical function implementations
single or double character identifiers are a bad idea.
I think the rule is that variables should be clear, readable, and not
misleading ... so it depends a lot on context. In general, shorter
is better as long as it's very obvious what the variable is ... so if
a variables's scope is larger (many lines), it needs to be longer and
more descriptive.
I disagree that in general, shorter is better. In my view, more
apparent and descriptive is always better than terse or cryptic.
Trying to work with legacy C code taught me that in spades.
My point was/is that, very often shorter == more apparent and
longer/more-descriptive is less apparent/readable ... it varies with
circumstances ... so I think it's not an area that can be reasonably
ruled upon. The aim is to make things clear/readable. I'm not
advocating terse and cryptic any more than you are advocating verbose
and obfuscated.
Fine. We're mostly agreed. I'm just really against single letter
identifiers for the non-mathematical case. Always. That was really the
point that I was making, even if I wasn't so clear about it.
As I said, both are used internally and I think that situation is bad.
Thus, we should pick the one true style for this as part of the canon.
Can we agree that *one* method is better than two?
Yes ... but I don't think it's sufficiently better that one should be
insisted upon when people contribute. I think that the NeXT style is
overwhelmingly more common, so I prefer it, and it's no real trouble to
convert gnu-style function names to NeXT style ones.
Ahah!
Take a look at what you wrote. I take it that you're saying that the
NeXT style is the standard and gnu_style_function names should be
changed to comply. Isn't that so?
Well in this we differ. For code to be readily readable by everyone
I'd say that:
if (cond)
{
body
}
is every bit as readable as:
if (cond)
{
body
}
Fundamentally yes, but people get used to particular styles and then
find the alternatives unclear.
There are also cases (mostly misuse of spaces) which I consider
fundamentally difficult to read,
and others apparently do not, so perhaps tghey are habit too...
if( cond ){
body}
Blech! I don't like that one, either.
Sorting out discrepancies and establishing rules is more important
from a software engineering view point than a simple question of
readability.
The two are inseparable imo. Readability is a major factor in
determining rules.
Yes it is. The rules, though, are about more than readability. (ie
readability is a sub-set of software engineering)
In writing code to be contributed I encountered these situations where
[snip]
I don't know about individual instances ... but generally when reviewing
patches I modify them to conform to our standards, and I guess I also
modify to conform to our general practices (eg names are NeXT style
almost everywhere, even if we don't formally say so in the standards).
Yes and I'm not trying to fault you for making the changes. You've
decided in your own mind that that the NeXT style is the way. Others
haven't. We don't have a decision. Let us collaboratively decide so that
we are being consistent and clear.
[snip]
Hence, I think we can have a No tabs rule and
Re: GNUstep Coding Standard Additions
--- Richard Frith-Macdonald [EMAIL PROTECTED]
wrote:
On 2005-04-30 08:05:03 +0100 Sheldon Gill
[EMAIL PROTECTED] wrote:
Secondly, I'd like the docs to clearly state the
source for
functions/methods
as OpenStep, MacOS (differentiate puma, jaguar,
panther and tiger) or GS
(version).
The current documentation does that for
Openstep/MacOS/GNUstep ... so
extending the mechanism to differentiate between
individual MacOS and
GNUstep releases should be fairly simple ... it's
just that it would take a
lot of time to review methods to find which release
each belongs to. I
guess we could extend the existing
STRICT_OPENSTEP/STRICT_MACOS_X
classification, but I think it might be better to
add gnustep and openstep
versioning as separate defines or as markup in the
comments. The advantage
of using defines and using #ifdef/#ifndef/#if
defined() is that people can
then easily check that their code does not use
features which are not
present in a particular version, however it's a bit
more cumbersome to deal
with.
That said, doing so for everything is a big
undertaking. To achieve this
someone will have to research the calls. I'd be
happy to baseline now so
that
calls are OpenStep, MacOS (panther) or GS current.
We already have that ... are you saying you would
review/check that all
methods are in the correct grouping? I think that
would be great (there
are almost certain to be some misclssifications) ...
but if you are happy to
review each method in the API, you could make the
classification more finely
grained (to release versions) if you like.
here is something i hacked up a while ago, wasn't
going to release it as it's fairly gross code wise...
anyhow its a bunch of tools,
methodlists generates either a apple.plist or
gnustep.plist
which contains all the classes found at runtime and
their class and instance methods
merge merges an apple and gnustep.plist into one...
and the rest do some sort of html output from the
merged plist...
although it actually works a bit strange..
for example on one platform we have,
@interface objectone : NSObject
- (void) foo {}
@end
@implementation objecttwo : objectone
- (void) foo {}
@end
on the another platform we have:
@interface objectone : NSObject
- (void) foo {}
@end
@implementation objecttwo : objectone
@end
it'll mention that one platforms objectTwo implements
-foo and the other doesn't.
anyhow, if someone wants to use this or clean it up or
whatever maybe it'll help...
matt
__
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com
methodlists-0.0.4.tar.gz
Description: methodlists-0.0.4.tar.gz
___
Discuss-gnustep mailing list
Discuss-gnustep@gnu.org
http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-04-30 08:04:57 +0100 Sheldon Gill [EMAIL PROTECTED] wrote:
Richard Frith-Macdonald wrote:
Functions, though, are much more ambiguous:
The NeXT standard is GSFunction() pretty much everywhere.
The GNU standard is gnu_function().
Both are followed internally in different places.
I try to stick to the GSFunction() style everywhere, and reserve the
underscore for macros.
Underscore for macros? Really?
In my view macros should be:
MACRO(x)
unless there is a very good reason otherwise.
I would use MACRO(X) or MULTI_WORD_MACRO(X) ... purely because macros are
entirely uppercase, which means you can't use capitalization of the initial
letters of words to make them more readable.
So your recommendation is
static NSString *
BundleObjectName(NSString *path, NSString* executable)
over
static NSString *
bundle_object_name(NSString *path, NSString* executable)
in this module private case?
Actually, my recommendation is to not force people to a single style when
contributing. However, our standard style would be without underscores (ie
the one used generally because it *has* to be used for the public api). I
think function names usually have a lowercase initial letter if they don't
have the NS or GS prefix though.
For ObjC object instances, the issue is less clear but should be
anObject generally. What if it's a single word? Object or object?
Variable names begin with a lowercase letter.
Excellent. We agree for that its object or anObject for all obj-c
variable instances.
I think the current standard isn't clear enough on this issue and should be
revised accordingly.
I think we should also be clear that dictionary or dict is preferred
over d. Except for mathematical function implementations single or
double character identifiers are a bad idea.
I think the rule is that variables should be clear, readable, and not
misleading ... so it depends a lot on context. In general, shorter is
better as long as it's very obvious what the variable is ... so if a
variables's scope is larger (many lines), it needs to be longer and more
descriptive.
I disagree that in general, shorter is better. In my view, more apparent
and
descriptive is always better than terse or cryptic. Trying to work with
legacy C code taught me that in spades.
My point was/is that, very often shorter == more apparent and
longer/more-descriptive is less apparent/readable ... it varies with
circumstances ... so I think it's not an area that can be reasonably ruled
upon. The aim is to make things clear/readable. I'm not advocating terse
and cryptic any more than you are advocating verbose and obfuscated.
As I said, both are used internally and I think that situation is bad.
Thus,
we should pick the one true style for this as part of the canon.
Can we agree that *one* method is better than two?
Yes ... but I don't think it's sufficiently better that one should be
insisted upon when people contribute. I think that the NeXT style is
overwhelmingly more common, so I prefer it, and it's no real trouble to
convert gnu-style function names to NeXT style ones.
Well in this we differ. For code to be readily readable by everyone I'd say
that:
if (cond)
{
body
}
is every bit as readable as:
if (cond)
{
body
}
Fundamentally yes, but people get used to particular styles and then find
the alternatives unclear.
There are also cases (mostly misuse of spaces) which I consider
fundamentally difficult to read,
and others apparently do not, so perhaps tghey are habit too...
if( cond ){
body}
Sorting out discrepancies and establishing rules is more important from a
software engineering view point than a simple question of readability.
The two are inseparable imo. Readability is a major factor in determining
rules.
In writing code to be contributed I encountered these situations where the
standards and guidelines weren't clear or conflicting. I had to make a
determination. That the source chose differently in various places points
to
others going through the same process. If there was a rule in place that
time
and effort would be saved.
I also note that you have modified source to move from one interpretation
to
the other. If your view was truly free to code as they like, why take the
time to do this?
I don't know about individual instances ... but generally when reviewing
patches I modify them to conform to our standards, and I guess I also modify
to conform to our general practices (eg names are NeXT style almost
everywhere, even if we don't formally say so in the standards). It doesn't
really 'take time' to do it ... as it's somethig I can do pretty
automatically, while thinking about the code to understand what it's doing.
Plus, if you take the time to move from one way to another then surely
someone else can come along later and move it back? Back and forth. Lets
decide, then move on.
2. I seem to agree with some of your suggestions, but disagree with just
as
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote:
Functions, though, are much more ambiguous:
The NeXT standard is GSFunction() pretty much everywhere.
The GNU standard is gnu_function().
Both are followed internally in different places.
I try to stick to the GSFunction() style everywhere, and reserve the
underscore for macros.
Underscore for macros? Really?
In my view macros should be:
MACRO(x)
unless there is a very good reason otherwise.
So your recommendation is
static NSString *
BundleObjectName(NSString *path, NSString* executable)
over
static NSString *
bundle_object_name(NSString *path, NSString* executable)
in this module private case?
For ObjC object instances, the issue is less clear but should be
anObject generally. What if it's a single word? Object or object?
Variable names begin with a lowercase letter.
Excellent. We agree for that its object or anObject for all obj-c
variable instances.
I think the current standard isn't clear enough on this issue and should
be revised accordingly.
I think we should also be clear that dictionary or dict is
preferred over d. Except for mathematical function implementations
single or double character identifiers are a bad idea.
I think the rule is that variables should be clear, readable, and not
misleading ... so it depends a lot on context. In general, shorter is
better as long as it's very obvious what the variable is ... so if a
variables's scope is larger (many lines), it needs to be longer and more
descriptive.
I disagree that in general, shorter is better. In my view, more apparent
and descriptive is always better than terse or cryptic. Trying to work
with legacy C code taught me that in spades.
Even when it is common parlance in a project I still think more apparent
is better. For example, I don't think that 'arp' is better than 'anARP'.
Rather, I'd go for 'aMemPool' or 'aMemoryPool'.
This, though, is moving from standard to style.
My focus for this post is to clarify ambiguities and establish doctrine
where we reasonably could.
{Doesn't mean I'm not up to continuing a thread on style ;-) }
What about static (ie local) variables? Especially if they refer to a
C type rather than an object. Consider
static int word_count; // GNU style
static int wordCount; // NeXT style
Both methods are used internally. I feel we should standardise on the
GNU style.
I stick to the NeXT style just like functions and classes.
You preference has been noted.
As I said, both are used internally and I think that situation is bad.
Thus, we should pick the one true style for this as part of the canon.
Can we agree that *one* method is better than two?
Conditional compilation
===
In trying to accommodate differences between platforms and particular
build requirements there is a lot of code which is conditionally
compiled using the pre-processor.
I recommend standarising on
#ifdef REQ_DEF
instead of
#if defined(REQ_DEF)
If you use defined(X) you can combine it with other checks using logical
operators ... which is much more powerful (and easier to read than
nested #ifdefs, so if yoiu have to have a standard, it should be to use
defined() rather than ifdef
Fair enough. Personally I quite like defined() and am happy to go with
that as the standard.
My recommendation was based purely on the first form being 50% more used
in -base.
Are there other coding standard issues which should be addressed?
I hate sounding negative about this ... but I think you are already
wanting to go too far.
Fair enough. I'm glad you're voicing your opinion.
1. People should be free to code as they like as long as we keep to a
sufficient degree of consistency for code to be readily readable by
everyone (and I think the code libraries have that degree of consistency).
Well in this we differ. For code to be readily readable by everyone I'd
say that:
if (cond)
{
body
}
is every bit as readable as:
if (cond)
{
body
}
and actually makes more sense from a logic and CS viewpoint. I'd also
say that:
if (cond)
{
body
}
is also better the second example. However, in contributing to GNUstep
I'm *not* free to make that decision. That's fine. Linux kernel
contribution goes
if (cond) {
body
}
but it doesn't matter either because the rules are clear.
Sorting out discrepancies and establishing rules is more important from
a software engineering view point than a simple question of readability.
In writing code to be contributed I encountered these situations where
the standards and guidelines weren't clear or conflicting. I had to make
a determination. That the source chose differently in various places
points to others going through the same process. If there was a rule in
place that time and effort would be saved.
I also note that you have modified source to move from one
interpretation to the other. If your view was truly free to code as
they like, why take the time to do this?
Plus, if you take the
Re: GNUstep Coding Standard Additions
On 2005-04-24 05:49:37 +0100 Sheldon Gill [EMAIL PROTECTED] wrote: There are a couple of naming standards in use. The trouble is that standard GNU form conflicts with standard NeXT and Apple forms. For ObjC methods the standard is verbClause or typeInitialiser. For ObjC classes the standard is NSObject. Yep. Functions, though, are much more ambiguous: The NeXT standard is GSFunction() pretty much everywhere. The GNU standard is gnu_function(). Both are followed internally in different places. I try to stick to the GSFunction() style everywhere, and reserve the underscore for macros. For ObjC object instances, the issue is less clear but should be anObject generally. What if it's a single word? Object or object? Variable names begin with a lowercase letter. I think we should also be clear that dictionary or dict is preferred over d. Except for mathematical function implementations single or double character identifiers are a bad idea. I think the rule is that variables should be clear, readable, and not misleading ... so it depends a lot on context. In general, shorter is better as long as it's very obvious what the variable is ... so if a variables's scope is larger (many lines), it needs to be longer and more descriptive. What about static (ie local) variables? Especially if they refer to a C type rather than an object. Consider static int word_count; // GNU style static int wordCount; // NeXT style Both methods are used internally. I feel we should standardise on the GNU style. I stick to the NeXT style just like functions and classes. Rather than recomment two different styles based on type I think we should use the same style for local objc variables as well. I stick to the capitalised style for all variables, methods, and functions ... very simple. Capitalizing the initial letter is for classes and public functions. Documentation commenting == Where should gsdoc comments go? When I wrote the gsdoc stuff, my idea was to put comments in the source code (rather then headers) so that it's as close as possible to where a programmer is working while writing and bugfixing, to amke it as easy as possible for them to add documentation. My theory was that this would mean that we got more/better documentation, and that this factor overrode any other issues such as the fact that putting documentation in the header is the more logical place. Now, after it's been available for a few years, it seems like I was wrong (it does not seem to have improved the frequency with which people document the code), so I regret having made that decision (coding autogsdoc was a whole lot more complex than it would have been if it only looked at the headers). If I was going to do it again I'd just put the documentation in the headers. Conditional compilation === In trying to accommodate differences between platforms and particular build requirements there is a lot of code which is conditionally compiled using the pre-processor. I recommend standarising on #ifdef REQ_DEF instead of #if defined(REQ_DEF) If you use defined(X) you can combine it with other checks using logical operators ... which is much more powerful (and easier to read than nested #ifdefs, so if yoiu have to have a standard, it should be to use defined() rather than ifdef We should also prefer positive conditional tests over negative ones. Hence Yes, but it's no big deal. In cases where the conditional block is reasonably large there must be comments at the appropriate points: Comments are good. Tabs vs Spaces == Its an age old debate but my experience is that tabs confuse things more than they are worth. Many programmer editors today support using the tab key to insert spaces rather than a tab character. They also support block indent/unindent. GNUstep uses the GNU 2/4 character indenting convention which doesn't match the use of 8 character indents most of the time. So IMHO using tabs isn't particularly convenient. Use of tabs can also confuse searches and diffs. Hence, I move that use of tabs be dropped. All in favour? I have no problem with tabs as long as they are set at the standard, 8 space intervals. Spaces are definitely better, but people obviously don't notice tabs (as they are invisible in most editors) ... so it's not clear how much good setting a guideline would be. However, I'm in favour of using spaces rather than tabs as a general guideline, since in my experience the correct use of whitespace and indentation is the biggest readability issue between the styles of competent programmers. Are there other coding standard issues which should be addressed? I hate sounding negative about this ... but I think you are already wanting to go too far. 1. People should be free to code as they like as long as we keep to a sufficient degree of consistency for code to be readily readable by everyone (and I think the code libraries have
Re: GNUstep Coding Standard Additions
Richard Frith-Macdonald wrote: On 2005-04-24 05:49:37 +0100 Sheldon Gill [EMAIL PROTECTED] wrote: FWIW... I believe that better specification of coding standards is a good thing. I don't have strong feelings either way for most of the issues mentioned. But I think we would get a lot more headway in this subject if we s/standards/guidelines/ suggesting that we won't reject/revert patches that do not conform, but that anyone can jump in and fix these issues as they please. Documentation commenting == Where should gsdoc comments go? When I wrote the gsdoc stuff, my idea was to put comments in the source code (rather then headers) so that it's as close as possible to where a programmer is working while writing and bugfixing, to amke it as easy as possible for them to add documentation. My theory was that this would mean that we got more/better documentation, and that this factor overrode any other issues such as the fact that putting documentation in the header is the more logical place. Now, after it's been available for a few years, it seems like I was wrong (it does not seem to have improved the frequency with which people document the code), so I regret having made that decision (coding autogsdoc was a whole lot more complex than it would have been if it only looked at the headers). If I was going to do it again I'd just put the documentation in the headers. Well I personally would also favor the comments in the implementation files but mostly because I like to look at headers to get a TOC-like birds-eye view of the class and in depth documentation obfuscates that. OTOH for certain usages (static inlines) there is no implementation file so for special cases like GSObjCRuntime, I'd rather have the documentation consistently in the header than scattered in both files. But I don't feel strongly about it either way. Tabs vs Spaces == Its an age old debate but my experience is that tabs confuse things more than they are worth. Many programmer editors today support using the tab key to insert spaces rather than a tab character. They also support block indent/unindent. GNUstep uses the GNU 2/4 character indenting convention which doesn't match the use of 8 character indents most of the time. So IMHO using tabs isn't particularly convenient. Use of tabs can also confuse searches and diffs. Hence, I move that use of tabs be dropped. All in favour? I have no problem with tabs as long as they are set at the standard, 8 space intervals. Spaces are definitely better, but people obviously don't notice tabs (as they are invisible in most editors) ... so it's not clear how much good setting a guideline would be. However, I'm in favour of using spaces rather than tabs as a general guideline, since in my experience the correct use of whitespace and indentation is the biggest readability issue between the styles of competent programmers. Well then, I claim incompetence! ;-) No, not a really big issue but I often deal with varying distributions with varying editors and is always a pain to get the indentation features set just right. If we decide on a standard here I'd be really really be happy if we could simply put some configuration files for some of the standard editors some place in cvs that we could copy into the HOME directory and then be done with it. I can see if I can come up with something for emacs. Cheers, David ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
--- Sheldon Gill [EMAIL PROTECTED] wrote:
There are some things which don't seem clear from the coding standards.
This has lead to things being done differently in various places. I
think it is a good idea to clean up and standardise.
Hence, I'm proposing a number of additions/clarifications with the aim
to make things clear and consistent.
Naming
==
There are a couple of naming standards in use. The trouble is that
standard GNU form conflicts with standard NeXT and Apple forms.
For ObjC methods the standard is verbClause or typeInitialiser.
For ObjC classes the standard is NSObject.
Functions, though, are much more ambiguous:
The NeXT standard is GSFunction() pretty much everywhere.
The GNU standard is gnu_function().
Both are followed internally in different places.
My recommendation is GSFunction() for API entry points and
gnu_function_style() for static local functions. This makes it very apparent
I agree with this.
For ObjC object instances, the issue is less clear but should be
anObject generally. What if it's a single word? Object or object?
I think we should also be clear that dictionary or dict is preferred
over d. Except for mathematical function implementations single or
double character identifiers are a bad idea.
What about static (ie local) variables? Especially if they refer to a C
type rather than an object. Consider
static int word_count; // GNU style
static int wordCount; // NeXT style
Both methods are used internally. I feel we should standardise on the
GNU style.
We should continue to use the NeXT style. It is the most prevalent in the
code currently.
I do have one other concern, although it's probably nothing...
When the .gorm or .nib model file loads on GNUstep (or OSX, since the process
is the same there), the establishConnection method is called on all of the
NSControlConnector and NSOutletConnector objects in the model. An
NSOutletConnector object uses one of two different techniques in
establishConnection to set the variable value depending on how the class was
coded:
1) It looks for a selector which can set the value. Something like setXXX
where XXX is the name of the outlet (e.g. if you connected to an outlet named
foo it would look for setFoo:). This is usually what happens in most
cases.
2) If the above selector isn't available, it will fall back to this method and
try to set the variable name directly using the
GSObjCFindVariable/GSObjCSetVariable methods in the runtime.
For any class which is forced to use option #2, if the outlet name is changed,
the model will have to be modified.
AppKit classes are very consistent in the sense that they always have the
appropriate setter/getter (so they will use #1, in 99.9% of the cases).
So we shouldn't have any problem there, I just wanted to mention the above.
Rather than recomment two different styles based on type I think we
should use the same style for local objc variables as well.
Documentation commenting
==
Where should gsdoc comments go? Mostly, it is in the implementation
files. To me, that seems the best place too. However, there are some
modules where all the gsdoc is in the header. Others use both, having
some in the header and some in the implementation.
There is no standard in place and I've noticed a few Changelog entries
where all the gsdoc is being moved from implementation to header.
I think that it shouldn't be in the headers. The reason is simple. The
implementation and the documentation need to match and keep in sync. If
you're editing the implementation, having the documentation right there
reminds you immediately of what it's supposed to do. It also makes it
easy to keep the two in synch. Mod the code, mod the docs.
The argument for having docs in the headers is essential ease of finding
the function/method prototype and usage information. That is what the
library documentation is for. That is precisely why we've got a
documentation tool and why we're using markup to make the documentation
better and easier to navigate. The real problem here is accessibility
and navigation through the docs. Once we have editors that have
auto-completion and built-in doc navigation it'll become a non-issue.
I agree with this.
Conditional compilation
===
In trying to accommodate differences between platforms and particular
build requirements there is a lot of code which is conditionally
compiled using the pre-processor.
I recommend standarising on
#ifdef REQ_DEF
instead of
#if defined(REQ_DEF)
We should also prefer positive conditional tests over negative ones. Hence
#ifdef REQDEF
{block A}
#else
{block B}
#endif
is preferred over
#ifndef REQDEF
{block B}
#else
{block A}
#endif
In cases where the conditional block is reasonably large there must be
comments at the appropriate points:
Re: GNUstep Coding Standard Additions
I think we should also be clear that dictionary or dict is preferred over d. Except for mathematical function implementations single or double character identifiers are a bad idea. Ahm ... yes, single or double character identifiers are very difficult to search/replace, and are generally obscure/unreadable. But to make them better, the best thing is to replace them with meaningful (self-commenting) names. Eg, 'threadLocalDictionary' instead of 'd'. 'dict' is not much of an improvement over 'd'. Still, stuff like 'i' or 'd' make sense for loops or temporary variables used shortly when it's very clear what they mean. In those contexts they might even be easier and clearer to read. I think you should never have more than 1 or 2 of such temporary variables though ... if you have more you need to give more meaningful (self-commenting) names else it gets confusing ;-) All this is very much un-formalized, probably we shouldn't have anything about that in our coding standards. After all, the GNU coding standards already say that variables should have meaningful names (I think/hope it says that), and that's really all we need. :-) Where should gsdoc comments go? Mostly, it is in the implementation files. There are different opinions on this matter ... ;-) Some people don't use autogsdoc and they just read headers. :-) Eg, I tend to do that for third-party libraries when I don't have time to figure out how/if their customized documentation system works and/or where/how I can get the documentation. The headers are always in the same place for all software, and they are guaranteed to contain the function / symbol you're looking for. If they also contain comments on what those are supposed to do, bang!, in no time you're on your way to fix things. Also, it seems like this is one of the few things that C gets right: you have a public header file declaring the API, and a private implementation file implementing it which is compiled and turned into object code. So the documentation of the public API should go in the public header file, while the documentation of the private implementation should go in the private source file. I suppose it's mostly up to the people writing the documentation though (not me at the moment). Anyway as a user I vote for having it in headers. :-) Thanks ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 2005-04-24 05:49:37 +0100 Sheldon Gill [EMAIL PROTECTED] wrote: There are some things which don't seem clear from the coding standards. This has lead to things being done differently in various places. I think it is a good idea to clean up and standardise. Hence, I'm proposing a number of additions/clarifications with the aim to make things clear and consistent. I've added (to the coding standards in cvs) all the suggestions which don't appear contentious ... please haver a look and let me know if I added anything I shouldn't have. ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On Apr 23, 2005, at 10:49 PM, Sheldon Gill wrote: Naming == There are a couple of naming standards in use. The trouble is that standard GNU form conflicts with standard NeXT and Apple forms. Sure, that all sounds fine. Documentation commenting == Where should gsdoc comments go? Mostly, it is in the implementation files. To me, that seems the best place too. However, there are some modules where all the gsdoc is in the I agree, but several other people don't, so this might not be resolved anytime soon. Conditional compilation === In trying to accommodate differences between platforms and particular build requirements there is a lot of code which is conditionally compiled using the pre-processor. I recommend standarising on #ifdef REQ_DEF instead of #if defined(REQ_DEF) Well this doesn't seem like it is confusing as it is, but I don't care either way. Tabs vs Spaces == Hence, I move that use of tabs be dropped. All in favour? Sure. Proper indentation, regardless of the viewer makes things much easier. ___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
Hello,
On Sunday, April 24, 2005, at 06:49 AM, Sheldon Gill wrote:
There are some things which don't seem clear from the coding standards.
there always are,
The NeXT standard is GSFunction() pretty much everywhere.
The GNU standard is gnu_function().
Both are followed internally in different places.
I would follow the NeXT style almost everywhere. For consistency.
By the way, when I first turned to objective-C I was essentially pleased
that my own informal coding standard was so close to it. SO maybe I am
biased.
For ObjC object instances, the issue is less clear but should be
anObject generally. What if it's a single word? Object or object?
I'd use object. It is an instance, instances start smallcaps.
static int word_count; // GNU style
static int wordCount; // NeXT style
Both methods are used internally. I feel we should standardise on the
GNU style.
why? I'd use NeXT style. It is internal, so let's use our style!
Conditional compilation
===
In trying to accommodate differences between platforms and particular
build requirements there is a lot of code which is conditionally
compiled using the pre-processor.
I recommend standarising on
#ifdef REQ_DEF
instead of
#if defined(REQ_DEF)
We should also prefer positive conditional tests over negative ones.
Hence
#ifdef REQDEF
{block A}
#else
{block B}
#endif
is preferred over
#ifndef REQDEF
{block B}
#else
{block A}
#endif
I would say the preferred method would be that the first clause should
be what is thought standard or default. In case of doubt though,
positive is recommended.
In cases where the conditional block is reasonably large there must be
comments at the appropriate points:
#ifdef REQDEF
{block A}
#else
{block B}
#endif /* REQDEF */
I would always put this if it is more than a couple of lines. Putting it
since the beginning makes sure that even after further coding which
might involve adding more lines, the end is clearly marked.
Tabs vs Spaces
==
Its an age old debate but my experience is that tabs confuse things
more than they are worth. Many programmer editors today support using
the tab key to insert spaces rather than a tab character. They also
support block indent/unindent.
GNUstep uses the GNU 2/4 character indenting convention which doesn't
match the use of 8 character indents most of the time.
So IMHO using tabs isn't particularly convenient. Use of tabs can also
confuse searches and diffs.
Hence, I move that use of tabs be dropped. All in favour?
I don't know what openstep did. Unfortunately many editors, like the
all-time favourite VIM and VI, tend to be tabs-friendly making a mess.
Nedit can be taught very conveniently to behave both ways very woell.
Apple's code-editor inside IB has both options and comes in default with
4 spaces and I find it very reasonable, but I really wonder what NeXT,
OpenStep and Apple (objc/cocoa) standards are and if they chnaged.
-R
___
Discuss-gnustep mailing list
Discuss-gnustep@gnu.org
http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On 24/04/05, Sheldon Gill [EMAIL PROTECTED] wrote: Are there other coding standard issues which should be addressed? Two suggestions: 1. Remove the (dangerous) use of if ([obj boolMethod] == YES) replacing it by if ([obj boolMethod]) 2. All method calls made through an IMP ahould have a comment showing the objc syntax of that method call. That would improve the readability of the code and maybe refrain some early optimisations. Benhur___ Discuss-gnustep mailing list Discuss-gnustep@gnu.org http://lists.gnu.org/mailman/listinfo/discuss-gnustep
Re: GNUstep Coding Standard Additions
On Apr 24, 2005, at 12:49 AM, Sheldon Gill wrote:
There are some things which don't seem clear from the coding standards.
This has lead to things being done differently in various places. I
think it is a good idea to clean up and standardise.
Hence, I'm proposing a number of additions/clarifications with the aim
to make things clear and consistent.
Most of your suggestions I agree with. Comments below on some other
ones..
Naming
==
...
For ObjC object instances, the issue is less clear but should be
anObject generally. What if it's a single word? Object or
object?
The latter is standard in Java and should be in ObjC/NeXT/Apple-land.
Otherwise when you see a method call you don't know if it's a class or
instance method. (Among other problems.)
I think we should also be clear that dictionary or dict is
preferred over d. Except for mathematical function implementations
single or double character identifiers are a bad idea.
For multi-word class names, some people like to use initials, as in
NSDistributedNotificationCenter dnc = ...;
Personally I think this is essentially as bad as single-character
identifiers and should explicitly be recommended against.
What about static (ie local) variables? Especially if they refer to a
C type rather than an object. Consider
static int word_count; // GNU style
static int wordCount; // NeXT style
Both methods are used internally. I feel we should standardise on the
GNU style.
In Java, NeXT style is used for these, but since in ObjC they really
are regular C variables rather than anything OO, perhaps C style is
better.
Rather than recomment two different styles based on type I think we
should use the same style for local objc variables as well.
Hmm. Contrasts with the standard for naming object instances. Are you
proposing to name object variables using one convention and primitive
variables using another? Seems like it might be confusing. In
addition, though I can see the argument for marking these differently,
it loses the marking of class/C variables which I think has better
potential to reduce errors than marking primitives.
Documentation commenting
==
Where should gsdoc comments go? Mostly, it is in the implementation
files. To me, that seems the best place too. However, there are some
modules where all the gsdoc is in the header. Others use both, having
some in the header and some in the implementation.
As you know this is a long-standing issue. I don't have a strong
opinion and agree with your points here for the most part. You seem to
be saying that users of the GS APIs should be consulting HTML GSdoc
whereas developers of the APIs should not have to do either this or
open up a header file. I guess this makes sense to some extent. But
what about class clusters? When the impl is in a subclass, the GSdoc
still has to be in the main source file, right above a '[self
subclassResponsibility]' line. This eliminates the developer
convenience for modifying the gsdoc and moreover might lead to cases
where GSdoc is accidentally put in the subclass (and never found). The
header method keeps everything in the same, known place, and can serve
as a backup when neither source code nor HTML-ized GSdoc is readily
available. Logically, it declares the contract that the implementation
must live up to.
Conditional compilation
===
In trying to accommodate differences between platforms and particular
build requirements there is a lot of code which is conditionally
compiled using the pre-processor.
I recommend standarising on
#ifdef REQ_DEF
instead of
#if defined(REQ_DEF)
Is there an equivalent for
#if defined(REQ_A) || defined(REQ_B)
in '#ifdef notation'?
We should also prefer positive conditional tests over negative ones.
Hence
#ifdef REQDEF
{block A}
#else
{block B}
#endif
is preferred over
#ifndef REQDEF
{block B}
#else
{block A}
#endif
Not sure about this. Following this convention could sometimes make
for less readable code.
Tabs vs Spaces
==
Its an age old debate but my experience is that tabs confuse things
more than they are worth.
Fully agree here.
___
Discuss-gnustep mailing list
Discuss-gnustep@gnu.org
http://lists.gnu.org/mailman/listinfo/discuss-gnustep
