As someone with a bachelor of science in computer science (almost), we spent quite some time on how to organize yourself when working on software, to make it easier to work together.
This document will contain my advice and experience on this subject. This topic is obviously completely subjective and the best way is different for individual and every team, still I hope
this document will have some value in development, and if I ever work in a team I will make sure they have read this.

So let me start by giving a list of what benefits you get out of your programming by following this document:

**Readability**- not only for others but also yourself (some of you might recognise 'I wrote this but I don't know what it does anymore')**Maintainability**- kind of goes together with readability, makes your code easier to maintain**Extendability**- it will be easier to add new things to your code, not just by you but even by people that haven't seen it yet.- Probably some more stuff, but you can make that up yourself.

Use one, any kind.

If you have no idea what a repository is, read my dota 2 version control guide.

Good practice when commenting is asking yourself about sections of code 'is it immediately obvious what this bit of code does?'; If the answer is not 100% yes:

So far for the obvious part, now come the 'secret tricks' of the academic programmer. This might seem like just a lot of extra work, but if you have (tens/hundreds of) thousands lines of code this will help, trust me.

```
--[[
Raises a base number to some power.
Author: Perry
Input: a - the base, a > 0 ; b - the power
Output: a + b
]]
function Power( a, b )
...
```

Now the nice thing is that contracts ALWAYS hold, so other contributors know what the function does in case they want to use it, and on top of that they get a guarantee that
as long as they adhere to the input specs, they will get the correct output as defined. If this is not the case, they know what author to blame. Some more things you could add
are pre- and post-conditions, the variables this function modifies, or more extensive descriptions of the different parameters. I do not recommend putting in all those, you will
not be happy (unfortunately I know this from experience too, this is nice but too much is very annoying).
Not as important as function descriptions, still useful. At the top of each class add a little description of the class, what it is used for, and who the main author is. You can do this in a few lines only.

What you should **always** do when working on a project with multiple programmers is defining and agreeing on some kind of standard. This standard can be as detailed as
needed, but here are some things you probably should define (you can add anything you like to these yourself!):

Some related guidelines:

- Use descriptive names for variables and functions

- Try avoiding code duplication, if you find you are repeating lines of code, move them to a seperate function

- Watch out for name collisions

--[[ Add a vector to this vector. Author: Perry Input: vec - some valid vector Output: this vector's length after the addition ]] function Vector2:Add( vec ) --add the x and y component of the other vector to the components of this one self.x = self.x + vec.x self.y = self.y + vec.y --return this vector's length return self:Length() end --[[ Returns the length of this vector. Author: Perry Input: - Output: this vector's length ]] function Vector2:Length() --Use the Pythagorean theorem return math.sqrt( self.x * self.x + self.y * self.y ) end --[[ Set the length of this vector to some value. Author: Perry Input: length - the length to set this vector to Output: - ]] function Vector2:SetLength( length ) --Calculate relative difference in size between the desired length and current length local factor = length/self:Length() --Multiply this vector's x and y components with the multiplication factor self.x = self.x * factor self.y = self.y * factor end