Tuesday, April 6, 2010

Changing Style and Code

Code is dynamic. You write something, and then you add something to it, then you modify some behavior, then you delete that crufty thing that you're not hugely proud of. Over time it grows and changes.

Coding standards and techniques are dynamic. You start with some basics, then you add a few things. Then you decide that the brilliant style idea you had wasn't so brilliant, so you modify your technique. Over time it grows and changes.

The really fun part is that you've now got (organic) code and (organic) coding standards and (organic) style, and they're all of varying ages and applications. If you change a piece of code you haven't touched in a while, it might not conform to your current coding practices in a lot of ways, even if the change you're making is really small. We have a few options here:
  1. Whenever we change a coding practice or style, we go through and update all the code.
  2. Whenever we touch a piece of code, we update the entire file/class/method to use the current style.
  3. We write all new or modified code in the current style, and don't worry about code you're not touching.
  4. We give up on coding standards. Or give up on our code. Come to think of it, this one is a bad idea. Skip #4!
Any of the first three options is viable. If you have a huge code base, or frequent style guide changes, then option 1 starts to take an inordinately long time. Option 2 or option 3 may be more appropriate.

If you stick with a code base for any period of time longer than a few months, you'll likely see code changes, and you'll likely see style changes. When that happens, you'll need to decide how to deal with it. You have choices, just be sure to make your choice so that your entire team knows what to do as things change.

8 comments:

  1. I think it depends on some other factors, like what the style change is and what your tools are.

    If the change is 'simple' and you have good tools, you might be able to do 1 for those changes.

    Certainly 3 is a minimum -- we need to move in what we currently think is the right direction.

    Some version of 2 allows you to get there incrementally, the question is again what the granularity is and how easy and risky it is to perform the change.

    One problem with updating code very slowly is that more often than not, existing code determines the style of new code more directly that abstract style guidelines.

    Another question is what things are worth encoding in the style guidelines, as opposed to practice.

    ReplyDelete
  2. Hi Catherine,

    I want just note that it is not very good idea to mix updating style and bugfixing/new feature development.
    It is simply not friendly for your SCM, and your definitely want your changes to be SCM-friendly.
    Thus I think that whatever option you choose, updating of style ("rejuvenation" of code) should be separate from "real" development.

    Best regards,
    Alexander Poluektov

    ReplyDelete
  3. Hi Catherine,

    I want just note that it is not very good idea to mix updating style and bugfixing/new feature development.
    It is simply not friendly for your SCM, and your definitely want your changes to be SCM-friendly.
    Thus I think that whatever option you choose, updating of style ("rejuvenation" of code) should be separate from "real" development.

    Best regards,
    Alexander Poluektov

    ReplyDelete
  4. Alexander,

    I'm not sure I understand what "friendly for your SCM" means. Can you help explain it?

    Also, why do you believe that maintaining the existing code with regards to style is not "real" development? I think of this as part of code maintainability; code that conforms to your style is easier for later devs to read and handle because it is more familiar. Is code maintainability not a "real" development goal?

    Catherine

    ReplyDelete
  5. Catherine,

    By "friendly for your SCM" I mean following:

    Suppose that bug was found, and developer is going to fix it. Developer then investigated that fixing that bug is just few-lines change. But code surrounding class/file/whatever should be updated because it was written in obsolete style etc. Then there are at least 2 scenarios for developer:
    1) s/he could fix bug, update style and commit these changes in one changeset
    2) or s/he could fix bug, commit it and update style at some point in future (maybe immediately, maybe never).
    Acting that way, developer increase traceability of his/her changes drastically.
    The same is applied for minor feature development.

    So what I'm trying to say is that you always should perform one logical change to code at the same time.

    Moreover, suppose that there are several branches of development. I bet you don't want to change your code in release branch just to catch up with style.

    > Also, why do you believe that maintaining the existing code with regards to style is not "real" development?

    I believe it is, and that's why I quoted "real" :)
    I just needed shortcut for "development that changes functionality of your code in either way" and choose (lame) term "real".

    ReplyDelete
  6. Alexander, I think I see on the friendly for your SCM thing - one thought process (fix a bug and update the style) might produce two changesets: (1) fix it; and (2) update the style. As you point out, it makes merges across branches smaller to have more atomic changes. I can be one work effort, though.

    Maybe "feature-oriented" or "functional changes" is what you're looking for with "real" development?

    ReplyDelete
  7. Catherine,

    > I think I see on the friendly for your SCM thing

    Yep, something like that.

    > Maybe "feature-oriented" or "functional changes" is what you're looking for with "real" development?

    Probably yes. Unfortunately I don't know process terminology well. Will catch up! :)

    Have a nice day!

    ReplyDelete
  8. Nice post, I was just thinking cannot custom-lint tools help in this regard?

    ReplyDelete