More comments in code – esp. stylesheets – please!

Resolved deko
(@deko)

17 years, 10 months ago

I’m willing to bet that most folks on the WordPress development team have seen a default Apache httpd.conf file. The thing commented to the extreme.

How about following suit with wp code? Sure, it looks like crap, but it’s invaluable to us users.

Those of us who appreciate handsome code (myself included) will likely purge most, if not all of the comments in our production code while keeping a commented copy for reference. I do this with httpd.conf.

More comments (with ancillary tips and tricks) is especially needed is the default stylesheets.

I’m still wondering what hr { display: none; } is for.

How about a dedicated team of a tech writers assigned to a commenting overhaul of wp code and stylesheets? You know as well as I that the developers will never do it.

This would probably circumvent many of the entry-level questions flooding the support forums.

Viewing 9 replies - 1 through 9 (of 9 total)

PozHonks
(@pozhonks)

17 years, 10 months ago

You are part of the elite: you are not afraid of touching the code. Because you understand how a computer is working.
Most people are afraid, don’t care, have something else to do.
That’s why the admin panel has been created, for people who do not understand php, html, css, etc.
As for themes, it is the same. Now, with WP2, we have the possibility to edit some display “options” with some themes. So most people will not have to tinker it to suit their needs.
But, if you think that WP lacks a good user manual, see the Docs, one of the most documented I’ve ever seen.
http://codex.wordpress.org/Main_Page

Thread Starter deko
(@deko)

17 years, 10 months ago

Just a Regular Guy, actually. As for those who are blissfully ignorant of the code, they’ll never see the comments anyway so it’s all the same for them.

Sure, there’s some good docs here (I’ve contributed myself) but nothing beats well-commented code.

It’s really not too much to ask.

Thread Starter deko
(@deko)

17 years, 10 months ago

And I’m still wondering what

hr { display: none; }

is all about.

Anyone?

Chris_K
(@handysolo)

17 years, 10 months ago

That’s just CSS defining that <hr> should have no display.

Not to be confused with commenting WP’s core code.

Thread Starter deko
(@deko)

17 years, 10 months ago

Yes, but why should it have no display?

How is it being used?

What is it accomplishing?

Is this an IE workaround?

In what situation is it useful?

As for the core code, I’m getting familiar with it at this point. There’s a lot of flotsam in there.

my version is 2.0.deko

Cypher
(@cypher)

17 years, 10 months ago

I concur with the OP that commenting is very vital to any program. As a software engineer by trade, I fall into the category of coders that comments my code to the extreme, this leads to easier understanding for the future for myself or others who may read the code.

Unfortunately, commenting code takes a backseat sometimes to “hacking” at something to make it work..and then you say, you’ll go back and comment it, but you might have easily forgotten what that wonderful “hack” is doing..:)

Regards

jimhere
(@jimhere)

17 years, 10 months ago

hr { display: none; }

Maybe whoever made this css is using it as a “spacer”?

moshu
(@moshu)

17 years, 10 months ago

Guys, you have to go back to Kubrick 1.2.5 (or maybe even further in time) when that design/template was NOT included as Default with WP, but was a template for WP 1.2 – developed by binarybonsai.com.
In K 1.2.5’s wp-layout.css (as it was called for WP 1.2 templates) that line is already there. I suspect today it’s a “heritage” from there… Maybe the author could answer your question 🙂

Thread Starter deko
(@deko)

17 years, 10 months ago

I’m wrestling with my CSS at the moment and was wondering what the heck that line was for. From what you’ve said, it sounds like a legacy CSS hack.