The Author Online Book Forums are Moving

The Author Online Book Forums will soon redirect to Manning's liveBook and liveVideo. All book forum content will migrate to liveBook's discussion forum and all video forum content will migrate to liveVideo. Log in to liveBook or liveVideo with your Manning credentials to join the discussion!

Thank you for your engagement in the AoF over the years! We look forward to offering you a more enhanced forum experience.

drnealaggarwal (6) [Avatar] Offline
#1
I find the code laid out with interspersed comments a little difficult for my brain to parse. I prefer the comments to be on the same line.

I know it's a personal preference thing but what do others think about this? Here is some code in both layout forms. You can cut and paste the following into miniAudicle to see what feels better to you:

Tried cutting and pasting and it seems this text engine here strips out the spacing. My intention was to put the in-line comments all lined up under each other to the right of the code.


// Better Karplus-Strong plucked string
// interspresed comments

Noise pluck => Delay str => dac;
str => str;
// hook string into itself
441.0::samp => str.delay;
// round-trip string delay, 100Hz at 44.1k SRATE
0.98 => str.gain;
// set round-trip string delay to less than 1.0
1.0 => pluck.gain;
// "pluck" the string for the right amount of time
441.0::samp => now;
0.0 => pluck.gain;
// shut off the noise generator
5.0::second => now;
// let the string "ring" a bit


// Better Karplus-Strong plucked string
// in-line comments

Noise pluck => Delay str => dac;
str => str; // hook string into itself
441.0::samp => str.delay; // round-trip string delay, 100Hz at 44.1k SRATE
0.98 => str.gain; // set round-trip string delay to less than 1.0
1.0 => pluck.gain; // "pluck" the string for the right amount of time
441.0::samp => now;
0.0 => pluck.gain; // shut off the noise generator
5.0::second => now; // let the string "ring" a bit

Message was edited by:
drnealaggarwal
danbernier (22) [Avatar] Offline
#2
Re: code layout better like this?
That makes the lines a lot longer, which often looks good on-screen, but can line-wrap on the page, where the margins are tighter.

Maybe using extra line breaks would help? Here, the comment comes before the code:


Noise pluck => Delay str => dac;
str => str;

// hook string into itself
441.0::samp => str.delay;

// round-trip string delay, 100Hz at 44.1k SRATE
0.98 => str.gain;
timj (3) [Avatar] Offline
#3
Re: code layout better like this?
+1 for comments left aligned, above the code. Comments to the right can easily get missed.
beanat50 (3) [Avatar] Offline
#4
Re: code layout better like this?
I also prefer left aligned, above the code. However, drnealaggarwal showed the example with no spacing, and I think that spacing is critical for ease of associating comments with code, such as shown by danbernier. I think if every comment line were preceded by a space, readability would go way up, and help drnealaggarwal and others ability to use this style.
perry.cook (29) [Avatar] Offline
#5
Re: code layout better like this?
As this thread bears witness, there are two, often
strong, opinions on this topic. I myself (perry) favor
short comments on the same line, but tabbed out so
they all line up, but miniAudicle doesn't do tabs well.

Ge is dogmatically in the left-line-above camp, so that's
what we decided on for the book. Either way, comments
are good, if meaningful.