ClearCode Standards Project

Great idea Ben - looking forward to reading more :)
- John

I enjoyed the presentation and I not only agree, but admire your initiative.

The style you suggest is configurable for XML using Oxygen (http://www.oxygenxml.com/), provided you have Oxygen break attributes, which you can enable under preferences.

The formatting for XML (or in my case, MXML) is beyond description. The indentation and alignment are spot-on. The usability and consistency are excellent. Oxygen also orders your attributes alphabetically.

It would be wonderful if someone had a code beautifier for CF that had the formatting that Oxygen provides for XML, and that it adheres to the standards Ben proposes.

Note: I think your style suggestion applies more toward standard CFML than it does CFScript (which is fine with me).

Also, the standard color formatting for attributes, tags, and such isn't suggestive enough in any of the major IDEs. I'd like to see this initiative share colors formatting for the various iDEs to improve contrast and readability.

Ben,

GREAT presentation. I really liked that you explained why code readability is so important.

I have one concern -- and it's just that, not something I've thought through very well. With each attribute on its own line, is it hard to get a sense of the overall structure of code? I tend to get lost with lots of lines of code. Or do you get used to this quickly?

Anyway, I thought you did a really fine job on the presentation. Very well thought out, structured, and delivered.

I really like the way you're applying these concepts to the "usability" of code and you present it really well and really convincingly. In practice I don't think I could ever bring myself to write every attribute of every tag on it's own line, but as John mentions perhaps a good IDE should provide a code formatting/viewing feature such as this for those developers that find it useful... However, I know that's not the main point of the presentation, and I think everything else is quite sound and I can see the benefits in helping raise awareness of writing code to a presentation standard. Nice work :)

Oops, I meant to say as David pointed out in his reference to Oxygen (not John) :P

Writing some kind of formatter would be time consuming. It's a dedicated project unto itself, and Adobe's recent IDE survey suggested that a future 'broom sweep' of code is possible.

Some argue that DW does have CF Formatting, but it's pretty terrible.

For productivity, a code beautifier would be invaluable.

I'm loading the presentation right now, I'm stoked to check it out. I'm hoping some of what you got will rub off on to me.

Damn dude, you're a beast. That iPhone app got you swoled!

Hi Ben,
You should let Charlie Arehart know about your presentation as I think it's really good and should be on his UGTV site.
http://www.carehart.org/ugtv/
- John

@ben

I think i now know why they say "Programming is an Art"
Nice work...

Heh, I've been meaning to write up something similar to this for ages, about my own structure/formatting methodology.

The whole readability/usability motivation I'm entirely in agreement with.

But when it comes to a some of your actual interpretations... well, I think you're crazy. :P

It's a good sort of crazy: you're trying to be logical and sensible - you're just not completely successful. ;)

Some of the significant things in your presentation which I disagree with:

1. Scrolling
For me, scrolling is important - why? Efficiency.
My editor window fits 120 characters across, but only 40 lines down.

Too many linebreaks is wasting both the width and height, and takes longer to read.

The area of focus isn't relevant - eyes move far quicker than scrolling

Not making effective use of the screen slows down readability and makes it harder to reference surrounding code.

2. Comments
Pointless comments are a huge waste of time - again it just slows things down (both reading & writing).
Code blocks can (and should) be seperated with newlines - real whitespace, not grey comments.

I forget the exact wording, so hopefully I'm mis-remembering, but you mentioned something about being able to ignore comments - this is completely wrong.
Comments should be placed to explain things that are not obvious, and should never be ignored.

3. Commas
Something annoyingly ignored is commas. It's not just you - everyone seems to do it.
They're very important to readability, and yet everyone just treats them as if they're writing English language rather than code.

CODE COMMAS DO NOT (AND SHOULD NOT) FOLLOW ENGLISH GRAMMAR RULES!

Don't do x[comma][space]y:
Function( arg1,arg2,arg3 ) = not great
Function( arg1, arg2, arg3 ) = BAD
Function( arg1 , arg2 , arg3 ) = GOOD

This bugs me - it's not readable:
SELECT something,
something_else,
another_thing AS whatever,
and_this AS that

But with commas at the front, it helps readability
SELECT something
, something_else
, another_thing AS whatever
, and_this AS that

And it removes the whole "crap I added an extra column but forgot the comma" situation.

Anyway, as I said, good that you've at least got a structure, even though I don't agree with lots of it. :)

Hey, your blog stripped out all the whitespace in my comment! :(

It was particularly important for the query example there, so here's a screenshot showing what that should have looked like:
http://hybridchill.com/misc/query_structure.png

Any chance of supporting <pre>...</pre> or <code>...</code> tags?

+1 for having Charlie add this to his site - and consider doing this as a CFMeetup!!!!!!!!!!

Some good stuff here - but this is such a personal thing I think it's difficult to say "this is best". I used to like wrapping stuff but since I've begun using a widescreen monitor - I don't mind long lines of code as much.

But for things I read or change frequently - CSS, comments, body content - I do keep those wrapped. Stuff I write once and rarely change - I leave those unwrapped.

I do break up my scripts similar to you - but I tend to follow my SQL formatting and put AND/OR, commas, etc at the beginning of lines instead of at the end. I gotta have commas first :)

Looking forward to the cliff notes version!

YEAH BEN!!!! Great stuff. I have been formatting my code very much like you for a few years now but it's helpful th have something concrete to work from so you don't get lazy and make exceptions (i.e. sometimes I do scope variable in all upper case and sometimes just the first letter). I have read some blog posts that some people find your coding style HARDER to follow but I think that's because of the way they think, and they can easily be re-trained. I would be interested in hearing what your thoughts are on tab size because I set my editors for 2-space tabs because 4-space tabs seem to create too much horizontal line width (especially with multi-level hierarchies) and it seems to leave islands for very short tags or attributes.

Stick to your guns Ben, your visual orientation is right on and the parallel with print and web publishing is also right on. Other people are free to do whatever they want and have their own opinions but they would have to come up with much better arguments that Peter has to convince me.

David Buhler mentions having the tag/function attributes in alphabetical order. I saw Dreamweaver 8 do this before I switched to CFEclipse and I carried it over. I found that if the attributes are always in alphabetical order it's easier to find "missing" or misspelled attributes.

It's good to have a standard. There is room for more than one standard. for instance, I don't like commas first, some people do. fine. no problem. I don't think anybody is saying there is only one way to code. Ben has a standard I happen to like so I might change my style to meet his standard. For instance I never put the /> on a separate line before but when I started putting attributes in alphabetical order (perhaps too anal for some people) it meant moving or adding attributes to the end was easier.

as far as monitors go, it may be difficult to standardize on a physical programming environment but everyone has to have at least a 17" monitor right? A 17" flat screen probably has the clearest picture at 1280x1024 for a standard width... maybe a little less for a widescreen. I have a 20" monitor that I run at 1600 x 1200 and I get 16 lines and 130 columns on it.

Yes you eyes move faster than scrolling but Ben's point is the the eye has more difficulty scanning to the end of a long line then returning the the start of the next line than if you had a short line of code.

oops I meant 67 lines

(any chance of compiling your comments into a single post in future?)

>> but everyone has to have at least a 17" monitor right?
Not necessarily, but I feel sorry for anyone who doesn't. :)

At work I've got 2x17" at 1024x768 (crappy old graphics card)
At home my main screen is a wide 17" at 1440x900 (plus a secondary 19" at 1152x864).

The 120x40 characters is at home in CFEclipse with other panels - with a full-screen notepad-like editor, I get 200x65.
But anyway the point is that whatever configuration there is much more width than height.

A cffunction with six cfarguments taking forty or more lines, rather than just seven, is a waste of space and not beneficial to readability - I can't quickly see all names or types.
Example:
http://hybridchill.com/misc/cfargument_structure_example.png

As you can see - there is no scanning to ends of lines required here, and I can much more easily read the important bits of code.

I am explicitly talking about cffunction/cfargument here by the way - some tags do benefit from being across multiple lines, as do certain function calls.
Thinking a little about which ones, I think anything that has a name/value pair type of structure is something I do multiline.

I also find myself coding differently for different things.

CF - I like everything tight except for the occasional cfscript.

CSS - I like everything on it's own line, alphabetized.

jQuery - I like lots of lines and indented code.

SQL - I like stuff tabbed so it lines up vertically, and everything on it's own line.

Hi Ben,

Thanks for the great presentation to India CFUG (Hyderabad and Chennai ColdFusion User Groups). It will really helpful for the fellow developers here to practice better coding standards in ColdFusion. We are looking forward for your more guidelines on ClearCode Standards Project.

- Akbar

What's great about this is idea is that people are talking and thinking about how and why we need to write readable code. I tried rewriting some of my own code for comparison (I posted the results here: http://www.aliaspooryorik.com/blog/index.cfm/e/posts.details/post/clearcode-standards-in-practice-75)

It is important to have coding standards (even if it is just for in-house use) - this is one of the reason that I like frameworks, so that if your team changes or grows then a new team member should be able to pick up any of your projects without the added headache of learning the coding style as well.

What I'd really like is a way to stop designers opening my code and messing up the formatting :)

> As far as comments go, why would you say comments should
> never be ignored? If you go to edit a document you just wrote,
> do you always read your comments?

It's not a case of reading vs not reading.
If I'm familiar with a document, I read neither comments nor code (I'll scan function names / similar and jump to the relevant part).
If I'm not familiar it, I'll read both.

ie: Comments form an extra piece of syntax to help code make sense, and I don't ignore them in the same way I don't ignore <cfparam.../> blocks - but I will skip such blocks when they're not relevant to what I'm looking for.

.

> how often do you actually forget to add a comma at the
> end of each line of the SELECT statement

It's not something I do at the end of each line - it's when I'm adding extra columns on, maybe c&p from another query. A trailing comma is easy to forget about, until you get odd errors about missing/incorrect vars.
Also, I don't see them as different to logical operators or concatenation, eg:
<cfif Something
AND Something
AND Something
>

<cfset Bob = "This"
& "That"
& "So on"
/>

>
> what happens if you have more than just a SELECT

I generally don't.
If I'm hitting a database directly I might, but in permanent queries I don't tend to have a need to limit the number of rows.
For DISTINCT... I think a DBA once told me if you're using DISTINCT your joins are broken. (something along those lines).
Again, useful when doing quick queries directly, but not too common in actual code.
I think I have examples of both though, and I've either shifted things along further or wrapped the first line. Possibly both in different situations.

.

> For starters, you tab out your argument attributes to create visual alignment.

I space them out, not tab.
Tabs are for indenting only - any mid-line whitespace *must* be spaces or it wont line up with different tab stops.

>
> But the highlighting that is in place - did you add that? Or did the light
> blue-gray automatically extend past the quotes of the argument?

Sorry, should have said - I added that to help indicate how my brain sees it - I mentally see the column but there is no actual colouring in the editor.
(Although it is the type of feature which an ideal editor should be capable of)

> I feel that this is very similar in spirit to what I am doing with
> new lines - you are using white space to create proximity and
> organization - same goal, different means.

Indeed. We are definitely both attacking the same problem, despite the quite different final styles.

As long as you don't have "<?php" in your code, then there can't be that much wrong with it! (Cheap shot I know...)

Very nice idae. I have already tried it. Thanks

Thank you for posting this...also, thank the "other you" for posting this :)

Great presentation. I only had time to skim through it but loved what I saw!

--

+1 to Peter Boughton. I was going to say the same thing about treating logical operators like commas and putting them at the beginning of a line.

--

You may have covered this, but I've started paying more attention recently to how code formatting affects source control. Code formatted the way you describe makes beautiful diffs.

--

Scrolling is not so much of a problem if you can orient your monitor vertically. Just try it. It rocks. :)

You need triple monitors. 1x in horizontal widescreen and 2x in vertical widescreen.

1050x1680 resolution is perfect.

one thing I like about putting attributes in alphabetical order is that is works for everything: functions, arguments, select statements, so it's really easy to say to someone... just put everything in alphabetical order, you don't have to think and rethink (and then memorize) which attributes are "more important" and have someone else say "well I thought Type was more important than Name" or some other crap.

it might even make you think a little more carefully about your naming conventions.

This would be a neat option in most editors/IDEs - "Alphabetize attributes"...

Holy shiz Ben. You just saved me having to buy Christmas presents for a bunch of my friends. I'm forwarding your presentation to them instead.

For the record, you're dead on with the scrolling argument. I'm about 100% sure that research would back your theories up to the bank. There's no way you can read an 800 character-long line of code nearly as fast as you can read 8 100 character-long lines of code, scrolling involved or not. Just because your monitor can accommodate enormous widths of text doesn't mean it's physiologically easier for you to read them.

Ideally, IDEs would let you zoom in and out on code like you can in graphics editors, allowing you to zoom out for a broader, more explicit and descriptive overview of the literal organization and play of code than is possible with tools like CFEclipse's outline view, but until then, PAGE UP / PAGE DOWN and/or a scroll wheel are more than ample.

I'm going to try your techniques out for a month and report back on how much weight I lose.

I actually agree with 100% of your tactics except 1- the upper-casing of scopes and SQL. Oh, and that you prefer Homesite to Dreamweaver. Other than that though, damn son.

so then you would say put the name first and alphabetize the rest? I could probably accept that, it would be an exception though and the fewer exceptions to the rule the better.

Dumb question: Why does the order of attributes / named arguments / CSS properties need to be stable? What does it matter if one cfquery has name first and another has datasource first?

Ben, so do you alphabetize all of your CSS rules independently of their type in a singular list?

I usually separate HTML overrides(h1, div, td), id-based selectors (#divHotLadies, #tableLoginForm), and classes (.averageLookingLadies, .highlight) into three comment-segregated groups and then alphabetize them within that. Where the benefits of that really come into play is troubleshooting and debugging when you're knee-deep in cascade. As you work though all of the styling applied to a particular element that's having a weird effect that you can't figure out (usually browser-compatibility), it's helpful to be able to start from the outside in, and work up the style hierarchy.

Ah, gotcha. I've never tried that before, my attributes usually follow a natural hierarchy of visual implication.

Meaning positioning, layout, height, width, things that are potent enough that they could affect other elements come first.

Then sub-"positioning" styles like margins and padding and borders.

Then purely 'stylistic' styles, like colors and font-effects.

But really, there are usually so few styles applied to any given selector that alphabetization probably makes more sense (probably). I guess my attribute ordering just models my development process, and that seemed to stick.

I see your point, but at the same time I think that there is usually an absolute, unarguable best way to do most things, and I want to get to that point as soon as humanly possible in all of my professional endeavors and never look back.

Macho Man Randy Savage and Indiana Jones spent their entire lives pursuing that mentality, and I'm no different. And that's why your presentation was so exciting. The end.

One more thing. I felt like you really had something when talking about how commenting should tell a story, and when working with unfamiliar data (especially your own), that story should be easier to digest than the same-but-different story that your code itself tells, because you can read comments (English) better than you can read code (Portuguese), even if you are fluent in Portuguese. It was still your 2nd language.

I totally take the same approach, and a lot of the time I'll actually write out a comment narrative of everything I want to happen on a page before I start coding at all. I use list-type delimiting to reinforce structure, and as I go from item to item I have sub-stories of comments that describe each larger group.

Hopefully that made sense. For example, before I start coding I'll write:

!--- 1. Make sure an idItem was passed into the page ---
!--- 2. Retrieve data for the specified item ---
!--- 3. Display the item data to the user with editing controls ---

Then, as I go through and code the 3 sections, between 2. and 3. for example I'll have

!--- To users, items and itemPrices are a singular concept, retrieve all of the item's prices and return them with the item data ---

!--- Each item belongs to one category, retrieve and merge the category into the item record ---

And so on and so forth.

Where this really gets interesting is with varying-colored comments. With the current IDEs, the only way I've found to do that is by using multi-language comments together, usually HTML and ColdFusion.

Take a look at this screenshot.
http://fleet19.com/sharing/vista-3.jpg

Granted, there are side-effects. The document you send to users will have your HTML comments (unless you strip them out, which if you have a highly-capable, under-utilized server, DO IT. Along with all whitespace.

One last note. You mentioned that various techniques you use server the purpose of helping you VISUALLY SCAN through the code and consume its message or story more rapidly. That's what the standout gold comment background does for me. I put my major action summaries in bold gold, and the details and walkthroughs in a more neutral, less eye-stopping color, but one that still lets you visually treat them as related. Have you ever tried it? Solid-background colored commenting? It's one of the primary reasons I don't use Eclipse more. And one of the primary reasons commenting is fun, because it looks pretty.

Note: Ignore that actual code and comments. They don't make sense as-are. Just look at the structure, concept, and coloring.

That screenshot is from a long time ago and I was clearly OD'd on sugar at the time.

@Ben,

Looking at your div.note {...} rule, my eyes tend to focus on the values before the properties. Values are more visually distinct than properties (especially within an editor that gives different types of values different colors).

Also, looking at the CSS for this site, the vast majority of your rule sets have five or fewer property names. And the longer ones tend to be mostly "font-*: {default value}." I doubt that alphabetizing has as much impact as you think.

Patrick

You can use http://www.cleancss.com/ to order your CSS attributes alphabetically.

This sounds interesting - I´m looking forward to read more about that.

How do you set your comments to be italicized?

I'm using eclipse 3.3.1.1 with cfeclipse 1.03 but it's not obvious how it's done or where to set it. I'll poke around some more.

on a tangenital note the font you use might be of interest. obviously a personal preference, right? check out this thread on Brian's Blog: http://www.briankotek.com/blog/index.cfm/2008/4/3/Development-Tip-Change-Your-Coding-Font

Unfortunately in CFEclipse you can only control color - not font attributes for the editor.

Yes - just something Mark hasn't got to (yet). I know it can be done because Aptana has decent controls - color, bold, italic, etc over each of it's editors - CSS, HTML, etc.

Perspective I think.

Hi Ben,

As you all know I am HomeSite fanatic and it is pretty awesome. You can completely edit entire language schemes including foreground, background, bold, italic, and underline. The font size and family are controlled by the overall editor, not any given scheme. I do love my HomeSite :)

I couldn't agree with you more, especially the built-in reg-ex for extended search-and-replace ;-)

Hi Ben,

I did your methodology on a recent flex project and then attempted to do the same thing with CFEclipse on a ColdFusion project.

It was like night and day for readability for me. Thanks for showing me the light. It also encouraged me to learn a few more keyboard shortcuts for eclipse.

Unfortunately, your methodology is impossible with CFEclipse as you know. Given that Flex builder does it well, it is native to CFEclipse and can be fixed! I'm actually going to regress and try homesite+.

If adobe puts the effort in to the CF IDE for eclipse as they did for Flex Builder, I predict an immediate takeover of the entire industry for ColdFusion. Each and every PHP and ASP website will immediately convert to CF.