On 8 April 2010 20:29, Philip Olson <phi...@roshambo.org> wrote: > > A few thoughts that come to mind: > * Tagged as a code snippet
I'm against the idea of tagging user-contributed notes, whatever type they are. This isn't the place however to ramble on that particular topic sufficing to say I don't want it for snippets or anything else. > * Users rate it, 1-10 If this was amended to an up/down rating it would get my (up) vote, pending seeing it in action. Rated notes could help sort the wheat from the chaff in a way that chronological ordering just cannot do. > * Ensure the copyright/license stuff is clear Currently the only mention* of this sort of thing on the add-note page is in relation to letting us merge comments into the documentation proper. (* After a very cursory glance around!) > * Dealing with PHP version requirements? I would expect many of the people contributing code snippets not to know the precise versions under which their snippet should be labelled and looking up those requirements for anything more than a simple function call, or at all, might be asking too much. Assuming comments on notes are allowed, someone in-the-know could clarify the versions if folks are having trouble. > * Users comment on individual snippets? Yes please. > * Some notes will contain a lot of words with a small code snippet, what tag > is it? Waffle. :-) > Example of good versus bad: > * A piece of code is well written, about 20 lines, and is about creating a > password. It happens to use strlen() a couple times so is posted under > function.strlen. Good? Bad? Bad. I think the notes should be relevant to the manual page under which they're posted. The code should be demonstrating the use of strlen rather than demonstrating how to create a password—where would the latter go? Perhaps there will not be a clear distinction but to give a more crude example, I don't think any snippet using the concatenation operator should go under the string operators manual page! > > A few other questions: > * Let's say a piece of code is great, voted up, and uses 5 internal PHP > functions. Should we scan it, then automagically make the snippet linked to > the 5 manual pages? No. See my previous comment. I'd rather let the author decide (with some moderation of course) where their contribution lives. > * We don't plan on becoming a full blown code repository, or do we? Worth > worrying about? I think it is worth worrying about; with all this discussion I fear we're going to be placing more community-emphasis on the user notes, snippets, comments-on-notes-and-snippets, etc. than on (improving) the documentation itself. That might be a good thing (community involvement always is) or bad (it is *the manual*, after all). > * Should we suggest (not enforce) coding standards? Sure. If we're going after the copy-and-paste crowd then the code might as well be at least a little bit consistent. Whether people would follow whatever standards are suggested would be another matter entirely. > > And lastly, one problem about coding examples is how good practice can dilute > the example. So for example, while teaching people about $_GET['foo'] we may > end up with one of: > A) echo htmlspecialchars($_GET['foo'], ENT_QUOTES, 'UTF-8'); // Hello World > B) echo $_GET['foo']; // Hello World > > The (A) dilutes the idea of $_GET whereas (B) is clear. So which is the > better example? Probably (A) in this case but the point is it's not > straightforward. Both snippets are demonstrating different ideas (escaping output versus a simple example of using $_GET). It would help if when adding snippets, the reason for/behind it is made clear: am I just posting a super-simple example without caring for best practices or do I just not know better?
