Saturday, 6 November 2010

To re-factor or not to re-factor

That is the Question,

For the last few years I've been making the students work to a coding standard (by giving them a small amount of marks for doing so). This has a number of advantages

  1. All the code looks the same and makes it easier to integrate into a larger code base.
  2. Makes spotting plagiarism easier (especially with the citation rules)
  3. Prepares the students for real life working situations (our coding standard is based on two real world examples)
When the original standard was published the code base for ngl was based on OpenGL and SDL however this year it has all been ported to Qt as this seems to be the new standard for most animation apps.

The problem I now face comes from this section in the standard

Function Names

Function names have the first letter of each world capitalised, with no underscores between words.
For Example:
AddEntry
     

Where possible, functions/methods that return a bool result should have a name that looks like a question, eg
IsValid, HasProtocol, AreParallel...
     
Each function should be preceeded by a comment containing a brief description about the function (how it works, what it does) above the function body in the .cpp file.

All of the Methods  in ngl follow this rule, however when using Qt the following is the standard syntax
ui->m_initEdit->setAutoIndent(true);
ui->m_initEdit->setAutoCompletionThreshold(2);
ui->m_initEdit->setAutoCompletionSource(QsciScintilla::AcsAll);
ui->m_initEdit->setBraceMatching(QsciScintilla::SloppyBraceMatch);
ui->m_initEdit->setMatchedBraceForegroundColor(Qt::blue);
ui->m_initEdit->setMatchedBraceBackgroundColor(Qt::yellow);

This means we have a mixed standard in most programs, I could re-factor the ngl: lib but this would take a while and break quite a lot of legacy code (which is still in the process of being re-written anyway).

At the present my thoughts are

Positives :

  1. Makes all the code look the same and matches Qt style
  2. Will not confuse people when writing code as it will always be the same 
  3. quite like the looks of the Qt syntax
  4. Not issued much code to the students yet, and start the main NGL teaching in a couple of weeks
Negatives :
  1. I will take quite a while to convert things
  2. Could break quite a lot of old code
  3. I'm actually used to using the current method and would have to re-learn how I write things
  4. The actual Qt guidelines are not that good so can't use them wholsale 
Think I will wait until Monday and decide then.

4 comments:

  1. Eeenteresting...might take a bit to break the camel type habit though!

    I'm about to embark on some coding soon so I think I'll give a try to using your standards. I spose since I've been mainly doing python, there's obvious bonus that to a point it enforces readability. Hopefully wont be too much retraining for my weak mind. Let me know how much of a pain refactoring is if you decide to go for it.

    ReplyDelete
  2. think I'm going to go for the Qt style, I'm planning on doing a python version of the coding standard at some stage but not got round to it, will be mostly the same as the C++ one apart from the obvious python restrictions.

    Check out the new version of ngl as the python binding are quite useful, and it's all GPL open source now

    ReplyDelete
  3. Have you seen this http://doc.trolltech.com/qq/qq13-apis.html, vaguely related but quite a good article. I've used it as reference when doing some stuff at work.

    Jimmy

    ReplyDelete
  4. I have read that before but forgot about it quite useful

    Cheers Jimmy

    ReplyDelete