Guidelines For Tidy Programs?

I've recently been programming my own API, which is now at about 1000 characters. I went back to make alterations to old code and obviously, found it very hard to read.

As I am intending to share the code at a later point, I was hoping to find guidelines on what "tidy code" is. I'm not a programmer, so I've really very little experience in writing code, yet alone for other peoples' use. One thing I find hard to decide on is how many comments to put in, especially when i'm not sure what is and isn't obvious.

Also, sorry if there are posts for this already, but the word "tidy" doesn't get you very far with this search engine.

Any help would be fab,

Thanks in advance

Indent
Comment

That's what I do :)/>

This is a very large debate among many programmers. :D/>

1. Function calls. at every function definition it is a good idea to comment – What the function does in leymans terms. eg, – converts string to number.
then on a seperate line – How to call : apiname.tonumber(text) > the number value of text

so it is commented on usage and function of what each part will do.

2. Indentation - Important!! make sure your code follows indentation. I will not say that it is required but it makes code look nicer and it is easier to follow the flow of the code if it is properly indented… Plus it is easier to see any missed closing statements like "end".

3. commenting every line of code is not needed, but… lol… it helps explain what is happenening, I myself tend to over comment. But it makes understanding the process easier, but also increases the size of your program.

4. Commented code!!

--[[  description text 
write your code here..
--]] closing of comment

if you write each function inside a commented code like above… you can easily turn on and off features in your code by changing –[[ to —[[ I find this perfect for debugging and adding new features, you can release a new code update but leave your development code turned off. (work on new features).

5. Depreciated features… if you remove anything from your code… use the above mentioned commenting the code out to remove a feature. This means anyone who is still using that feature can just un-comment it.


I hope this helps a little in your process and development. :D/>

Also, I would add to albrat to use only functions when you need a piece of code multiple. I have seen many times people do this:

local function do()
   print("dsd")
end

do()
-- Never using it again

That is pretty much the same as:

(function()
   print("dsd")
end)()

It is valid in some places, but this is on its ambigious code an Lua doesnt accept that.

4 and 5 above are not good practice. Don't leave commented code in your programs after you're done testing around it. Get rid of it.