Re: GNUstep Coding Standard Additions

[Sheldon Gill]

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