Classification of "features we don't think are a good way of coding anymore"

#19

This is a good point. My initial thoughts when thinking about how this would be implemented in the documentation was having an editable deprecation description aside from the general description (to allow us to format it distinctly). Simply flagging something as deprecated, or “to avoid”, is probably not good enough (and will stoke flames).

For any deprecation, there would want to be a brief justification, links to the alternatives and links to any articles expanding on the new direction.

Would that be better than various deprecation statuses?

Edit: adding example

Something along these lines, but with distinct “Deprecated” formatting:

We could even automatically include a link to what “Deprecated” means in all deprecation notices.

1 Like
#20

Yes, @modius has a valid point in there being the need to provide additional information for both “avoid” and “deprecated” anyway. And I think it needs to be visually clear and easy to find - similar to what @dom_watson has posted.

Re the question if having this additional explanation voiding the need for the “avoid” status — I’m not sure. Need to think about and mull over it a bit. Will report back in a day or two.

#21

FYI: along this process we will also revisit all “deprecated” functionalities and change them to “avoid”, i think in most cases.

1 Like
#22

Since I was one of the strongest objectors to marking createObject() as deprecated, I’ll point to the C++ ANSI Standard definition of “deprecated”:

Normative for the current edition of the Standard, but not guaranteed to be part of the Standard in future revisions.

In 2012, there was a proposal to refine this wording to be more explicit:

Normative for the current edition of the Standard, but been identified as a candidate for removal from future revisions of the Standard

My emphasis.

A specific example is the register keyword which was marked “deprecated” in C++11 and followed up in late 2014 with a proposal to remove it from C++17.

Back when the ANSI Standards Committee overhauled the standard library and deprecated all the old .h header files in favor of the newer headers with no explicit .h suffix, our sense was definitely that those old .h header files would be removed from the Standard in the future (even tho’ that overturned decades of preceding C / C++ practice).

This is why I think “deprecate” should really only be used for things that are candidates for removal in the future.

I like the idea of “avoid” for something that should be discouraged so I like @micstriit’s position of changing all “deprecated” functionalities […] to “avoid”.

2 Likes
#23

Call it Avoid; it’s as good a name as any – especially if it removes the semantic debate around the definition of deprecated. My point is simply having two (or more) different states that mean effectively the same thing – avoid using – is a waste of effort.

Developers will have to read the documentation in any event to determine why exactly they are avoiding that feature. The documentation can give all the detail that is actually needed to make an appropriate decision about the features ongoing use, or the alternative approach.

What are the other C++ states beyond “Normal” and “Deprecate”?

#24

I’m coming to this party a bit late, but how about the redefine deprecated
to the ANSI understanding, as it seems to be the most common
understanding. Then add the 4th as “superseded”, instead of “avoid”. The
reason is keeping a positive spin on things. Devs (at least this one :slight_smile:
will look at a status of avoid and think, “why have a language feature at
all if I’m supposed to avoid it?” However if I see superseded, I’m getting
excited to learn a new approach to solving my problem.

4 Likes
#25

Good call.


Adam

#26

As I said in another post, I agree that developers would want to look up why something is Avoid or Deprecated. And the documentation needs to cater for this accordingly.

Regardless if there is a misinterpretation of Java’s Deprecated or not — I don’t think it is because what was quoted back then in the respective thread was a piece of documentation of how to use the documentation attribute “@deprecated” in Java and THAT was misinterpreted imho, but anyway —having a 4th status of Avoid that clearly makes a non-endorsed way of coding is valuable and after considering the options, I think it should be added.

#27

Yes, I’d be very happy to change my proposal to use “Superseded” instead of “Avoid” - that makes perfect sense.

1 Like
#28

@agentK while I’m happy to be convinced, I’m not seeing the value here. Perhaps you could offer 5 examples in the current code base where the term “superseded” (nee Avoid) would be used to good effect, over the existing term “Deprecated”.

The only thing that springs to mind for me is the createObject() controversy. In the presence of a separate dialect like Lucee Language, surely this would have resolved itself? That is, createObject() in the CFML dialect would remain until such time as Adobe decided to deprecate, if ever. And createObject() would not exist in the Lucee Language dialect at all, having been superseded.

@seancorfield am genuinely interested here in the status assigned by other languages.

If something is discontinued, the language team has flagged the desire to remove that feature at some time. The period a deprecated element remains in a language is a factor of how deeply entrenched it is in the community and the impact its likely to have once removed. So while the desire is there, the pragmatic reality is it may never be removed – only the documentation could explain the expected timeframe to developers.

I thought your position on createObject() was that “deprecate” clearly telegraphs the desire to remove the function, even if the underlying intent was to retain the function due to compatibility concerns. In retrospect, I’d agree you were right. The addition of a 4th status appears to be drifting away from the clarity of that argument.

Is it really a good idea to flag to developers that a particular feature has been superseded but it’s ok to continue using said feature. Wouldn’t this just lead to the build up of cruft we see in CFML today?

2 Likes
#29

In the standards world, there are generally just the two states: “normal” and “deprecated”. Deprecated features generally do get removed from future standards, sometimes in the next revision, sometimes in the revision following. There isn’t always a “better way” added to replace it. In the register example I gave, compilers just stopped needing to be given that hint.

In the Java world, deprecated is more for library authors to mark an API as “to be avoided” / “superseded” with a better way – a different signature of the same function is most common. Whether a deprecated feature is removed later is up to the library author. Java’s evolution is glacial so standard library functions marked deprecated tend to stay around for a very long time.

In the Clojure world, deprecated is used more in the standards sense, by both the language designers and library authors. Deprecated things do tend to go away (eventually).

Coming back to CFML / Lucee: “deprecating” createObject() in CFML is a bit silly since it’s just not going away until Adobe decide it is (which is likely never given their obsession with backward compatibility). For Lucee, you can just go right ahead and remove it – for the Lucee language, you can simply require folks do it a different way.

I don’t really see any point in “avoid” / “superseded” to be honest – that was more a suggestion to avoid the charged meaning of “deprecate” in a context where LAS do not intend to remove a feature (because compatibility).

@micstriit seems to want a way to label features as “undesirable” but without the intent to remove. If that’s the case, then “deprecate” is the wrong term, in my opinion.

1 Like
Coding standard or linter instead of quibbling over "deprecated" etc
#30

Sure:

http://docs.lucee.org/reference/functions/parameterexists.html
http://docs.lucee.org/reference/functions/nowserver.html
http://docs.lucee.org/reference/functions/createobject.html
http://docs.lucee.org/reference/functions/getk2serverdoccount.html
http://docs.lucee.org/reference/tags/servlet.html

Each of them is currently “deprecated” but will never be removed of Lucee’s CFML engine due to it waiting for Adobe do do anything with them and Adobe won’t because they rather die than breaking their big US govt client’s crappy CF 4.0 codebases (ParameterExists).

They should all be superseded/avoid instead of deprecated unless Lucee’s CFML implementation will deprecate them in 1-2 versions.

Regardless, such a flag describes the reality. The word “avoid” also made it very clear that it’s NOT ok to continue using said feature and that there are better ways.

#31

What would we gain from changing the status of those functions from “deprecated” to something else?

#32

Clarity. Please read the initial post and the scenario description:

#33

I’m a little confused here @justincarter as you’ve quoted @agentK but Discourse shows this as a response to my post?

My opinion on @agentK’s post would agree with @justincarter I think: I see no point in labeling those features as anything other than “deprecated” since that’s what Allaire / Macromedia / Adobe has decided (regardless of whether they ever will remove them – given they’ve floated ACF12 might not be entirely backward compatible, I guess we can hope?).

I think the Lucee language can “do the right thing” here and simply remove things that folks would like to see “deprecated” / “avoided” in CFML. After all, if we all agree something is “bad” and that the Lucee language provides a “better” way, why bother supporting the old, bad way at all? That’s why I think labeling features of the Lucee language as “avoid” (or whatever) is a bit pointless: just omit them.

Not sure if that answers your question?

#34

I don’t know if it provides any clarifty for CFML functions that are marked “deprecated” by Adobe?
http://help.adobe.com/en_US/ColdFusion/9.0/CFMLRef/WSc3ff6d0ea77859461172e0811cbec22c24-64b5.html

For createObject, let’s just drop it from Lucee Lang :wink:

1 Like
#35

I believe this was done in the context of CFML dialect still being the principal language of Lucee. Since that time LAS come around to a more concerted view that Lucee Language will have to be the principal way forward; trying to evolve CFML without Adobe is just too hard a task.

With that in mind I imagine @micstriit would have no issue reverting createObject() to normal and hiding the suite of createComponent() et al functions that were to supercede it in CFML. And then having createObject() struck from Lucee Language entirely.

But I think you are making my argument for me.

The point of Lucee Language is to give us the opportunity to evolve our own CFML implementation. That said, the CFML dialect should strive for compatibility with Adobe’s official CFML offering. Lucee should not be making any determination about the CFML dialect that is not in line with Adobe CFML. If Adobe has these listed as “deprecated” then we should also list them as “deprecated”, otherwise they should be normal.

We should never be recommending an unofficial alternative in the CFML dialect. We should only be providing features on the CFML dialect in line with the features available in Adobe CFML and with the syntax dictated by Adobe CFML.

#36

I’d certainly be more than happy with that course of action :smile:

#37

Just to make things very clear: This proposal was talking about CFML the way forward, not about LuceeLang.

#38

Sure, that’s another way of solving it.

However with @modius saying that:

the consequence would be that the current CFML implementation in Lucee 4.5 would have to be trimmed back in Lucee 5 to exactly what ACF offers in their CFML implementation, right?