Gentle Editing

Like many programmers, I’ve come to love Stack Overflow and the rest of the Stack Exchange network. Its unique Wiki / Blog / Forum blend creates a fantastic platform for knowledge sharing.

Thanks to its Wiki-like editing capabilities, quality sticklers like myself can get stuck in and help to smooth out some of the rough edges of the content base.

Unfortunately we geeks sometimes allow our egos to get the better of us, resulting in reasonably common, dreaded, edit wars.  To avoid these, I’ve come up with what I feel is a very gentle and respectful editing style which I’d like to share with you today.  My edits always take a fair bit of time, but I feel it’s worth the investment in the interests of the greater good.

Be respectful. This is the most important part of editing.  Whatever changes I make, I always consider the original poster and try to get a feel for what message they were trying to convey.

The spirit of the post. Whenever I make an edit, I’m very careful not to change it so drastically that the meaning could be altered.  Any change I make should not alter the spirit of the post in any way.

Different flavours of English. I happen to have been taught British English, and as such write words like colour, centre, flavour, and favourite.  However, I will never impose this on others.  I will never change a person’s spelling of a word to a different style of English.  Again, this comes down to respecting the writer.

Edit once. Apart from reading the whole post before submitting my edits, I never come back to an edited post.  Edit once, and move on.  If others feel that further changes are necessary then so be it.  Communities that are as active as Stack Overflow tend to flow in the direction of what is right, so I really think people shouldn’t feel that they need to take it upon themselves to make sure that the post conforms to their personal standards.  This is what being part of a collaborative community is all about.

One’s editing goals should always be humble.  Edit for clarity.

 

K&R – Solution to Exercise 1.23

I’m working my way through The C Programming Language at the moment, and so far I’m loving C’s purity and leanness.

One of my few disappointments with the book is the lack of solutions to the exercises. The exercises are refreshingly challenging because the book isn’t aimed at beginning programmers. Unfortunately this means that the desire to validate one’s solutions is quite strong. Fortunately, Google had a solution to this problem: Richard Heathfield’s solutions site.

I just finished my solution to exercise 1.23 (“Remove all comments from a C program”) and I’m quite chuffed with it so thought I would share it here. Out of the multiple solutions provided on Richard’s site, mine was about the closest to following the guidelines as far as what knowledge one is supposed to have of C by that (early) point in the book (the only thing I cheated with is the use of break and continue – it would have just been quite ugly without those two small additions). Basically the solution is a state machine using if / else instead of more traditional switch methods as switch had not yet been introduced.

My solution deals with all the special cases I could think of, and even deals with the tricky sample input on Richard’s site, provided at the bottom of the solutions page for this exercise.

/*
 * K&R Exercise 1-23
 *
 * "Write a program to remove all comments from a C program. Don't
 *  forget to handle quoted strings and character constants properly.
 *  C comments don't nest."
 *
 */
 
#include 
 
int main()
{
    int c;
    int c2;
    int in_quotes = 0;
    int in_comment = 0;
    int current_quote;
 
    c = getchar();
    while (c != EOF)
    {
        if (!in_comment && !in_quotes)
        {
            if (c == '\'' || c == '"')
            {
                in_quotes = 1;
                current_quote = c;
                putchar(c);
            }
            else if (c == '/')
            {
                c2 = getchar();
                if (c2 != EOF && c2 == '*')
                {
                    in_comment = 1;
                }
                else
                {
                    putchar(c); /* Just a regular '/', so output it. */
                    c = c2;
                    continue;
                }
            }
            else
            {
                putchar(c);
            }
        }
        else if (in_comment)
        {
            /* Check for a closing comment. */
            if (c == '*')
            {
                c2 = getchar();
                if (c2 != EOF && c2 == '/')
                {
                    in_comment = 0;
                }
                else
                {
                    /* Don't advance to next character in stream. */
                    c = c2;
                    continue;
                }
            }
        }
        else if (in_quotes)
        {
            /* Skip over escaped chars. */
            if (c == '\\')
            {
                putchar(c);
                c = getchar();
            }
            else
            {
                /* Check for closing quote. */
                if (c == current_quote)
                    in_quotes = 0;
            }
            putchar(c);
        }
 
        c = getchar();
    }
 
    return 0;
}

Users Are Not Stupid

Really!  And, quite frankly, I’m sick and tired of programmers talking about them like this (not all programmers, some are worse than others, and all the usual disclaimery stuff applies)

I’m a user first, programmer second.  So are you.  Chances are you were using a computer for everyday tasks for a while before you started programming.  The fact is, we will never again be able to see computers in the same way as we did back then.  This is why we have average users test our software, and it’s vital that we do so.

Think about what it means to be a programmer.  Our job is to make computers more accessible to our dear users.  Everything we do, we ultimately do for them.  If we code with the user in mind at all times, and respect their needs, then everybody will ultimately be better off.

Sure, sometimes (hell, often!) a user’s request may not feel like the right thing for the system, and sometimes it won’t feel like the most elegant thing to do, but there are times when a leap of faith is required.  There will always be a balance between what users want and what we feel is good for them, but I’m appealing to you to lean in the direction of the user.

Nobody likes validating input to death, or putting up what seems like endless tooltips and hints all over the place, but users really do appreciate the little things we do to make their experience better.  Unfortunately, it’s more of a case of preventing outrage than garnering actual praise, but that’s what we signed up for, for better or worse.  The more people use the system for its intended purpose and the less we hear back, the better.

Make your error messages friendly.  Let the user feel like they have a more casual relationship with the system and they might feel less frustrated when something goes wrong.

“Don’t you worry about blank, let me worry about blank.”

Customer service rules apply even when the customer isn’t right in front of us.  Think of the system as an extension of yourself.  Build a little bit of your personality into the system for a more personal experience.

Please, please don’t think of your users as < you, it’s just not fair.  Think of how out of place you would feel in their profession.  Respect the average user, and let’s make the computer experience better.  For them.