discuss-gnustep
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GNUstep Coding Standard Additions


From: Sheldon Gill
Subject: Re: GNUstep Coding Standard Additions
Date: Thu, 05 May 2005 17:33:26 +0800
User-agent: Mozilla Thunderbird 1.0 (Windows/20041206)

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 with the docs.

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.

Hmm... let me see. Does it:

a) Let new-comers easily read and understand
b) Help in the design phase, prior to coding
c) allow people not confident in source modification to contribute

Using the defines in the headers has two advantages over adding explicit markup in the comments -
1. Less work to do generating the markup.

But potentially more effort in maintenance and checking.

2. Compile time compatibility checking is available.

The alternative I propose allows checking an application's imports against a list. The one check could generate a report of compatibility against multiple targets, including those you have no direct access to.

I could compare the imports of my windows application here on my windows machine and discover that it uses calls from MacOS 10.3 which weren't implemented until gnustep-gui 1.0.2 and so on

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.

I believe we'll gain much more than lose.


Regards,
Sheldon




reply via email to

[Prev in Thread] Current Thread [Next in Thread]