Revise Examples so that they follow the style guide.

[zelf0]

Increasing Access

Consistency across examples and documentation increases cognitive accessibility.

Most appropriate sub-area of p5.js?

Examples

Feature request details

Examples should all follow the p5 style guide.

[zelf0]

@nickmcintyre I will start working on this issue soon

[nickmcintyre]

Sounds good @zelf0! Feel free to suggest revisions to the style guide as you work.

[zelf0]

@nickmcintyre Hey, I'm getting around to working on this, a lot of the examples need punctuation, grammar, and clarity edits to fit the style guide. But the other thing that's against the style guide is using // for multiline comments. I started changing it to /*, but I don't see an explanation in the style guide for why /* is better than //, so I'm wondering if I should just keep the //s and suggest a revision to the style guide because I personally feel that // is more common anyways and just as good. It's very possible there's a reason the style guide suggests /* over //, I just don't know what it is. (Also if that's the case, I would suggest for the reason to be indicated in the style guide like some of the other guidelines have)

[nickmcintyre]

@zelf0 nice! Thanks for bringing this up.

I believe most major programming languages have a dedicated syntax for multiline comments because it's tedious and error-prone to remember // for things like function descriptions. Modern IDEs make writing documentation with /* pretty nice.

All that said, let's discuss some specific examples. I think it'd be fine to use // for comments that span 2 or 3 lines. I'm curious how often comments that are more than ~3 lines appear. My sense is that the example code should be clear enough that big multiline comments (more than 3 or 4 lines) generally aren't needed.

[limzykenneth]

Just to note there is a bit of nuance when it comes to multi line comments, mostly in terms of convention as JS don't really care that much about comments.

This style is usually quite common especially for shorter text, the reason being this is usually what text editor do by default when commenting lines with Cmd/Ctrl + /.

// Some comment that
// go onto the next line

This is the default way of doing multi line comments, the only thing that matters is /* */ pair of symbols. Adding and removing them is usually not as easy as the above.

/*
Some comment that
go onto the next line
*/

This style is doing the same thing as above with JS only caring about /* */ pair of symbols, however the beginning /** is used by many documentation engine to differentiate between documentation (which starts with /**) and regular old multi line comments not meant to be documentation (starts with /* only). The additional decoration at the beginning of each line (*) are usually optional and just makes things neater.

/**
Some comment that
go onto the next line
*/

A small side effect with the third documentation comment style with decoration at the beginning of each line is that it is a bit more difficult to copy multiple lines of text without also copying the decorations (unless your text editor support a particular style of text highlighting):

/**
 * Some comment that
 * go onto the next line
 */

[zelf0]

Right, so the style guide seems to be preferring that last way, with the * in the front of each line, which does seem a little tedious, but if that's the preferred way, there are a bunch of multiline comments, mostly using //, so I can change them all over to the /** if that's preferred.

[nickmcintyre]

@limzykenneth thanks for helping us to better understand the common patterns for comments. The various forms of /* have their place, but perhaps not in example code.

@zelf0 thanks again for bringing this up, and for helping us to keep it simple. I think typing * on each line isn't much of an improvement over //. It also introduces a possible syntax barrier for beginners. What do you think about opening an issue to change that style guideline with a rationale along the lines of "Using // for all comments increases consistency between examples."? Or something like that.

I found a few examples with comments that span several lines, such as edge detection. In this case, there are 42 lines of comments and 34 lines of code. What do y'all think about the length of the comments and the ratio of comments:code?

[zelf0]

I think it's ok to have a high comments:code ratio if it's necessary. If I find examples where comments are too wordy, I'll simplify them. And it's possible some examples require more comments because they are overly complicated, in which case we can create a new issue to replace the example with something more straightforward.

And I'll open an issue to change the guideline.

[zelf0]

Working in this branch: https://github.com/zelf0/p5.js-website/tree/edit-examples

In the Structure folder, there's an example called "Functions" But it seems to just be about the drawTarget() function. Should it be replaced with an example on functions in general, or should it be re-titled to "Draw Target"

[zelf0]

Also, what do you think about using destructured assignment to condense consecutive variable declarations? For example, I came across this line in the examples:

let [total, child, young, adult, senior, elder] = [577, 103, 69,
   122, 170, 113
 ];

And I'm wondering if it should be changed to:

let total = 577;
let child = 103;
let young = 69;
let adult = 122;
let senior = 170;
let elder = 113;

[nickmcintyre]

@zelf0 thanks for pointing this out. I think the current functions example could be improved in a couple of ways. It'd be helpful to demonstrate different patterns for parameters (none, a few, and defaults). It's also easier to focus on functions without loops or other other control flow structures present.

I also agree about avoiding destructuring–your change looks good!

[nickmcintyre]

@RohitPaul0007 here's some of the conversation regarding comments.

What do you think about editing a subset of the examples to bring them inline with the style guide? The examples in the Hello p5 section could be a good place to start.

[RohitPaul0007]

Well if it is one line comment one should use "// ". But if it is multi line comment, where some one is trying to explain the code one should use "/* */ ". In this way it becomes more readable code base. @nickmcintyre

[nickmcintyre]

@RohitPaul0007 you're welcome to suggest a change by opening an issue. We recently came to a different conclusion as you can see from the discussion above. The style we use in our documentation breaks with some common patterns when it's helpful to beginners.