A footnote for the next time you think, 'How could they have coded it this way?'

<< Google Notebook | Home | Moving and data migration >>

A footnote for the next time you think, 'How could they have coded it this way?'

I've been amused lately by many of the "WTF were they thinking when they wrote it" posts I've been seeing lately, especially on CodeBetter. This came to mind as I looked at a Word doc I was vainly trying to convert to HTML for posting. No, don't worrry, this isn't another rant about Word 2003's "HTML" output. Instead, it is what people do when they are formatting documents. Here's a excerpt:

Arial, 18pt Bold (1 instance)
Arial, 10pt Bold, Gray (2 instances)
11pt bold, before 6pt (5 instances)
Arial, 13pt Bold, Double line above (18 instances)

etc.

In short, we have a document where the formatting has been done piecemeal. "The code" (if you will) has been hacked together without subroutines, naming conventions or other planning. Using styles isn't simply a good idea, it fulfills the same purpose of proper code formatting -- it makes maintenance and refactoring of the "code" easier and less error-prone. The number of times I've heard, "I deleted one character, and everything reformatted" is a side-effect of this behaviour. Word can be downright messy about all those little formatting codes you're forcing in there.

Having a clean stylesheet, and learning how to use it, is not just helpful, it's yet another sign you care about quality.

I remember back to "the days" when I would get submissions from authors for MSDN. There are some authors I would look forward to working with their documents, although I'll admit that it was partly as I'd always learn something from reading the work of Scott, Bill, Dino, Stephen, Steven, Karl, Victor, Michele, etc. Their code was clean, and so were their docs. The MSDN editors would frequently note that "there was little they had to do" to get the documents ready for publishing. Back to this document, I've started on it three times today, and I keep pausing (such as this post) as it's mind and soul hurtful work.

So, the next time you feel like complaining about a bad sample or coding technique, remember that there are other examples of sloppiness and incorrect technique out there.

Print | posted on Friday, May 19, 2006 1:28 AM

Feedback

# re: A footnote for the next time you think, 'How could they have coded it this way?'

left by kent at 5/20/2006 2:29 AM

Hmmm. There's a good feature request - refactoring for documents. Like it.

# re: A footnote for the next time you think, 'How could they have coded it this way?'

left by Anonymous at 5/19/2006 4:18 PM

I deal with more WTFs than not...it's sad, depressing, stressful and I hate it. It's why I blog about it so much - gives me a chance to vent. I'm sure though that I'm going to retire from programming early because of it :(

As for word, you're absolutely right. I can't imagine using Word without the "Style And Formatting" sidebar open. And there's nothing worse than having to work on someone else's document, opening the sidebar and realizing that they don't have a clue.

Come on people, not only does it improve the professionalism and readability of your document, but 1/2 the features and word work off proper formatting.

I want to cry....

# re: A footnote for the next time you think, 'How could they have coded it this way?'

left by craiger at 5/19/2006 5:15 PM

Perhaps the tool needs to be a bit more intelligent in this case, like once you use a particular font+size+decoration a few times it goes "I should make this a style for them".

Or maybe you could make a macro which scours the doc and turns common formatting into styles?

# re: A footnote for the next time you think, 'How could they have coded it this way?'

left by Anonymous at 5/20/2006 11:30 AM

And to bring the discussion full circle, even if you do use a style sheet in Word, when you Save As HTML, it doesn't do a particularly good job of interpreting those styles. My particular beef is with bulleted paragraphs -- for some reason, it does not turn those into ul/li sets. Whatever.

As for Word not being smart enough to have Clippy pop up and say "I see that you're using this formatting a lot ... would you like me to make a style out if it?", that is indeed a good idea. An alternative that we use is to lock the styles down -- you *must* use preexisting styles. Sounds pretty restrictive, but when you (ultimately) are writing to an XML schema, it becomes darn useful.

# re: A footnote for the next time you think, 'How could they have coded it this way?'

left by kent at 5/20/2006 8:30 PM

Oh, yeah. I wanted to avoid ranting about that Save as "HTML" feature that's supposed to be there, but you started it. :P

The lack of ul/li formatting is the worst, I agree. I remember when they started that internal 'suggestion' list, and I ranted to it. I was told that "They'd rather ensure complete fidelity with the original doc than actual HTML accuracy." (or words to that effect. To insert a ruddy pack of

<![if !supportLists]>·        
<![endif]>Bulleted text here<o:p></o:p>

AND WHAT'S WITH o:p?!?!?!! Augh!
I need to sit down and count to ten again...

Comments have been closed on this topic.

Kent

Post Categories

Archives

Image Galleries