Code explanation area

[damian1301]

After many hours of sitting around each night, looking through merlyn's webtechniques column, I thought it would be a great idea to have one of those here.

Basically, all it would be is:

1. Someone posts their code
2. Posts brief explanations of each line down below

Of course, these posts would be lengthy at most. But, considering mischief's post earlier (auto <readmore>), we could just use his idea to conserve space. There may also be some problems with vaque explanations and bad code which could all be fixed by a healthy reply or /msg.

This idea might be able to be put into check in the code catacombs. Whereas all vroom has to do is add a textarea for the explanation and all.

Overall, this seems like a great learning experience, better than any spoiler posted on a japh. Anyway,isn't that why we are all here?

UPDATE:As dws mentions below, this is what I was trying to get through

Almost a Perl hacker.
Dave AKA damian
I encourage you to email me

[dws]

As one whose path of the Perl learning curve was helped considerably by close study of merlyn's Web Techniques articles, I think this a really good idea, but I think that it's good in a non-obvious way: The act of writing narratives for code can help the code itself.

Finding that a section of code is hard to describe in prose is often a good indication that the code needs reworking. It's like walking someone through your code. I often come across places where I have to say "Hm... It would have been clearer if I'd written..."

I've gotta believe that would help some of the code that gets posted.

[t'mo]

"The act of writing narratives for code can help the code itself."

A la Look at my CD's!; check out 'Update' number 2... However, I'm not sure that we need a separate 'room' in the Monastery to do this.

[footpad]

It's not a bad idea, but I'm not sure we necessarily need another area. Certainly any code post could contain commentary, in the form of comments or even POD.

Also, many monks provide extensive details in their more-thought out posts. Consider Ovid's Death to Dot Star! or chromatic's Common Regex Gotchas. Also, Dominus's home node provides links to his site, where he's mirrored many of his articles.

It takes a special combination of skills to be able to explain code and to craft it. These skills must be nurtured and deeloped if you're going to gain any decent respect from your peers. Or, at the very least, any respect from the person who has to maintain your code.

In other words, it's a discpline thing, a skill you'll develop as a programmer. Feel free to document your code as completely as necessary--especially if you're counting on bits, behaviors, or sublties of the language that might be confusing to inexperienced coders or lesser mortals.

In short, we should already be doing this, save perhaps in Ob-Fu, where working through the confusion is the learning exercise.

--f

[a]

Or convince some of the more saintly monks to run through some of the tougher CPAN modules. Perhaps tutorials would be a good place for this, w/o creating a new area.

a