Do we - as a community - really want to be encouraging tag-based CFML code anywhere other than in views, in which case most doc examples for functions should be using script?
This is a good example, but it doesn’t actually give the output of the code. It should, shouldn’t it? The pendant in me things the array and struct variables should be called arrayValue and structValue to be uniform with the rest of the example, but that’s of little consequence.
Oh, a third question…
Is there a doc page that is the “model” / “ideal” example of how it should be done, and another docs page which does like a screen cap of that and has arrows pointing at the various bits saying “do it like [this], because of [that]” and “see how we’ve done [this thing here], it’s because then [some excellent benefit]”? That could be really helpful. I’m sure you’ve got in mind exactly how things should work to be ideal, so it might be good to document that too?
There isn’t, but there should be - that’s a really good idea. I’ve created a task: [LD-46] - Lucee
There are also some omissions in the IsBoolean() examples there. I’m going to be implementing Daemon’s design soon and will ensure there are edit links to help make editing these docs far easier.
@adam_cameron do you have any particular preference as to how output should be indicated. i.e. whether the example should be some code that writes output, and having comments to suggest the expected output; or something more like: IsEmpty() :: Lucee Documentation where we see, ‘each of the following statements evaluates to true’?
Another consideration is how to document different types of function / tag. What is appropriate for a “decision” function may not be for other types.
G’day:
I hope it’s not too soon to follow this up. But you did ask.
Is that no to this:
Or to this:
?
Cool, cheers.
I don’t think this is great code, really:
isEmpty() by itself already evaluates to a boolean, and it’s a general guideline to not do a boolean to boolean comparison, so it’s tacitly encouraging bad practice. Plus it’s simply tautological clutter in this case.
isEmpty("") // true
I also like to avoid comments, as I also think comments - in general - are a bad practice. However that’s a better option than the bad-practice code example above.
In my blog examples I tend to have this sort of thing:
dump([
isEmpty(""),
isEmpty({})
])
Then show the dump. I’m not entirely convinced this is the correct approach.
Some language docs use an assertion to demonstrate things, eg:
result = isEmpty([])
assertTrue(result)
I have raised a ticket to get assert() added to CFML: LDEV-60.
But I’m not convinced by that either.
If CFML users were used to using the CLI or a REPL instead of a webpage, one could just capture the output from the REPL. This is a tactic I’ve often seen used. How heavily is Lucee going to encourage REPL / CLI usage as “a thing”?
Am I helping yet?
I reckon of the options I mention here, comments are preferable:
isEmpty(0) // false
Or the REPL option.
Other than the godawful equal spacing of the parentheses (why Dom, just why? ;-)), yeah, that’s a clear approach.
Another consideration is is it isBoolean() or IsBoolean()? I know Adobe documents these things with an initial capital, but that’s a bit of an odd standard, isn’t it? Perhaps not on-topic here. Is it worth starting a thread about a CFML coding guideline from Lucee? I might include this para in another thread.
No, I don’t think we should be encouraging tag based CFML in examples
Agreed re not a good thing to do generally - was thinking that it bought quick reading clarity without needing comments. I think you’re right though, the comments approach is cleaner and doesn’t spread the message that its ok to do == true.
I’ve always capitalized the first letter of system functions, this is a habit from a convention that I first learned when learning C a long while ago - custom application functions and object methods would be headless camel case. The vertical alignment is something I picked up and have stuck with, it’s all about the Gestalt (allows the brain to more easily pick out and relate content together). That said, not sure that this practice is widely enough adopted to be promoted in the docs.
I’ll try to formulate a guide on code examples - will have a look at good docs sites to see what works best, though there will always be a subjective argument.
I’ve always hated the way ACF docs listed code without the results. So showing results is important, but what about having the code snippets as gists that with just a click get evaluated in something like trycf.com (or a Lucee sponsored version of such that ensures current and perhaps past versions?) That way, not only can you easily see the result of executed code, but can also quickly try something out that is a bit of a tweak from the provided example.
I kinda like the idea of Gists but for two things:
fragments the docs
makes for more complex build process when building the docs for PDF, offline versions, etc.
That said, the idea of running the examples in TryCF or something similar definitely appeals and I think we can achieve that using what we have already (we have total control over how code highlight blocks are rendered and could make it happen). I’ve contact Abram to see what we could achieve.
Great! I only mentioned gists as I had thought Abram had already built in the ability to run a code sample through a link to a gist, so was thinking low barrier to entry.
Great job so far! I like how things are starting to come together.
