Table of Contents
Clockwork Coding Standard
Anybody is free to make a copy of this standard, or modify it in any way – even use it as your own!
In many ways standardization is an important part of any programming. The most important part of a coding standard is to make sure all code is easily readable and modifiable by other programmers in the team.
One major benefit of following a coding standard is that it will aid in speeding up the rate at which the program is created, by allowing the programmer to quickly realize what is going on with a specific line of code.
File names must [in most cases] be named by whether they are ran on the server, the client, or are shared.
e.g: sv_filename.lua, cl_filename.lua, and sh_filename.lua
Documenting code is good, but overuse of comments can really ruin the aesthetics. All comments should be well punctuated and typed properly so other programmers on the team can read and understand them.
Comments should be used when a piece of code is difficult to understand immediately, or to describe what a function does.
Every function should have at least one comment summing up what that function does or is about, but it is recommended that for functions directly related to Clockwork, a block comment is used to give specific detail on it.
Here's an example of bad commenting:
\\ -- Kill the player.\\ player:Kill();\\
It's pretty obvious that this doesn't need a comment, it explains itself.
Function names should always start with a capital letter for each word, and describe the function as well as possible without it become ridiculous. The arguments within the function should be reasonably described, or there should be information on the argument in the comment(s) above it.
Here's an example of bad function naming:
\\ function killtheplayer(player) end;\\ function KillThePlayerAndReturnTheTimeItTook(player) end;\\
Here's an example of good function naming:
\\ function KillThePlayer(player) end;\\
All scope variables should be named in camel case, there are no exceptions to this rule. All variables of type boolean must have the ‘is’ prefix or ‘b’, or ‘should’ prefix. All scope variables must be initialized, there should be no uninitialized values as it can cause problems and unexpected outcomes down the line.
All scope variables must also be reasonably descriptive, and if it is not possible to describe the variable reasonably then a comment should be made describing its purpose.
Here's an example of bad scope variables:
\\ function KillThePlayer(ply, respawn, respawntime)\\ ply:Kill(); if (respawn) then\\ ply:Respawn(respawntime);\\ end;\\ end;\\
Here's an example of good scope variables:
\\ function KillThePlayer(player, shouldRespawn, respawnTime)\\ player:Kill(); if (shouldRespawn) then\\ player:Respawn(respawnTime);\\ end;\\ end;\\
* Always use four space tabs.
* Always finish a statement or command with a semi-colon.
* Never put spaces after or before parenthesis or square brackets (unless a function call is within those parenthesis).