PSR-5 provide a way to indicate if a method result is cached or not
jclaveau opened this issue · comments
I work on a lot of models those times and realized it would be nice to be able to characterize methods by the fact their results are cached or not.
An @cached tag, maybe associated with the caching interface used.
For example :
@cached instance (If the result is stored in a property)
@cached class (If the cache is stored in a static property)
@cached (The name of the class making the interface with redis, memcache or whatever)
I've seen nothing proposing it so I hope this idea is not just totally dumb :)
Note that this PSR is pretty much dead as of now. However, to reply to your actual request. This tag would, if it is even useful in a broader sense, need to be called @memoized because that is what it is about. That being said, the exposure of the place and/or technology that is actually taking care of the memoization results in leakage of an implementation detail that should be documented with other means. For example design documents. The problem with such tags is that they tend to get outdated too fast and their usefulness diminishes too fast.
Thanks for the quick response and the precision!
if it is even useful in a broader sense, need to be called @memoized because that is what it is about
If I understood well, considering instance properties, class properties or static variables it's memoization. For systems like memcache, Redis or local files, we're speacking about cache. I don't know if two different words would be better or not.
That being said, the exposure of the place and/or technology that is actually taking care of the memoization results in leakage of an implementation detail that should be documented with other means. For example design documents.
I totally agree with you but I'm currently working on an app that has been made four years ago by someone else without any technical document and I try to make it "more standard" and robust. As I start from almost nothing, beginning by comments is a far easier way to get an overview about it to be able to make technical documents in some time.
Which mean you're theoretically 100% wright but factually more or less wrong when we speak about sold product which has a lot of value for it's customers and a lot (more than a lot actually :) ) of code debt.
The problem with such tags is that they tend to get outdated too fast and their usefulness diminishes too fast.
I understand for the fact they get outdated quickly but not really for the usefulness. This kind of optimization can produce big loss of time when you code the tests (which is exactly what I'm doing these times) or during debug phases which make it extremely useful once the feature is implemented and is just a dependence of a new one.
Anyway, as this PSR is dying, this is not really important but thanks again for the answer, hoping my point of view can show you an other insight.
It sounds like your need is a temporary one, though a medium-term
"temporary". As such, I would not look for standardizing any approach that
helps you slowly build up your documentation.
That said, I can suggest how I might use what's available in phpDocumentor
to accomplish your goal. I would lean heavily on the "@uses" tag, and
create some dummy functions (whether in a class or standalone) to be the
target of these tags.
The functions are not real... they are solely to be constructs for your
"contexts" (e.g. "function cached()"). These will be your targets for the
"@uses" tags. Where you were wanting to put an "@cached", I would put
"@uses cached() {optional description of this one location's relevance to
using/being cache(d)}". This way, you have your "context marker" there at
your code that you wanted denoted as "hey dude, I get cached".
The bonus is the opposite end of the "@uses" tag. By having it point to a
dummy function that you let be included in your generated docs, you will
have a list of "@Used-By" tags showing all the places you put the "@uses"
tags that pointed to this dummy function.
I've used this technique to help highlight when a function/method is used
in the body of another function/method, to build up some "dependency"
tracking when working in legacy code.
CRB
On May 20, 2016 04:07, "Jean Claveau" notifications@github.com wrote:
Thanks for the quick response and the precision!
if it is even useful in a broader sense, need to be called @memoized
https://github.com/memoized because that is what it is about
If I understood well, considering instance properties, class properties or
static variables it's memoization. For systems like memcache, Redis or
local files, we're speacking about cache. I don't know if two different
words would be better or not.
That being said, the exposure of the place and/or technology that is
actually taking care of the memoization results in leakage of an
implementation detail that should be documented with other means. For
example design documents.
I totally agree with you but I'm currently working on an app that has been
made four years ago by someone else without any technical document and I
try to make it "more standard" and robust. As I start from almost nothing,
beginning by comments is a far easier way to get an overview about it to be
able to make technical documents in some time.
Which mean you're theoretically 100% wright but factually more or less
wrong when we speak about sold product which has a lot of value for it's
customers and a lot (more than a lot actually :) ) of code debt.
The problem with such tags is that they tend to get outdated too fast and
their usefulness diminishes too fast.
I understand for the fact they get outdated quickly but not really for the
usefulness. This kind of optimization can produce big loss of time when you
code the tests (which is exactly what I'm doing these times) or during
debug phases which make it extremely useful once the feature is implemented
and is just a dependence of a new one.
Anyway, as this PSR is dying, this is not really important but thanks again
for the answer, hoping my point of view can show you an other insight.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#131 (comment)
@ashnazg oO great approach! Thanks for the clear explanation!
Let's close this issue.
My main argument for @memoized vs. @cached is that the underlying technology simply should not matter and that a user should not care.
I did not say that you might not have a special use case, however, it is a special use case and should be solved by a special solution. I would not go for the proposed @use recycling and instead simply create a vendor specific tag. We (at our company) do that as well:
@{VENDOR}-{TAG}
e.g. @fleshgrinder-cached redis