Coding Conventions & Practices

The aim is to do the development in an agile manner. Basically loads of experimental code trying to get it to work, we can then worry about optimisations and code clean up later (this is referred to as technical debt that we should record in the issues with a label technical debt). Let me know if you think I am going too far in terms of a structured approach, but it’s an approach that works. For example, if I implement straw swaths, but I am using magic values, then I should record that in the wiki as technical debt, saying something like, magic value in call to setSwath should be changed.

This basically becomes a list of tasks that anyone can pick up when they feel like it and try to fix. In case you are wondering, magic values is a development term for using hard coded values without any explanations. Other options is to add comments in the code like --TODO: clean up these magic values. I actually normally do both.

Example:
SomeClass.DoSomething(onThisObject, 10)
-- 10  is a magic value. If another person comes to read the code, 
-- it will be hard to understand what the hell 10 is.

-- So this should be fixed to

local howManyTimes = 10
SomeClass.DoSomething(onThisObject,howManyTimes)

On this subject, in terms of coding practice, I would like to stay away from poorly named variables. There is nothing wrong with long and descriptive variable names. Instead of k,v, enum, j and whatever, use descriptive terms so that it’s easy to see what the code is doing.

Example:

For n = 1 to length(someArrayorTable) 
DoSomething(n)

Instead
For dog = 1 to length(someArrayorTable)
DoSomething(dog)