base
base copied to clipboard
redeclipse
Coding style?
Now that code development is open, what about adding coding conventions?
CONTRIBUTING.md is read automatically by GitHub and suggested to the user when submitting an issue or a pull request.
this is already on the agenda (probably before or around the time of release), but you know how things progress in this project.
personally i don't want to see any more code additions before the release and would rather have it as soon as possible, with the remaining large issues gone and out of the way. but that's just me.
I agree at some point there should be a definitive set of conventions (I already added a note regarding commit messages to the wiki) that detail what's expected, in order to avoid incidents like this one.
But yeah, after 1.5 and more things are sorted out :)
Yeah, I know that we need to come up with guidelines in this regard. For now, I just ask that any source code contributions be left to me to review and merge, at least until we get an idea of the things we will need to put in said guidelines. We will come back to this.
We need to come back to this, and at least come up with some official requirements which reflect the already-established coding style. I am not the most qualified to speak on all the coding standard minutiae, but here are some precedents I have seen:
- All code is indented with spaces and not with tabs
- Four space indentation (note that this is at odds with the official Cubescript standard of 3/indent)
- Engine code has opening brackets on their own line
- UIs have opening brackets at the end of the previous line
- Closing brackets get their own line, except in UIs with empty or small trailing arguments
- Static variables in all caps
- Internal UI vars begin with ui_
- Cubescript's implied else has its opening bracket on the same line as the if statement's closing bracket
- No empty line spacing for anything within brackets
Also should get more serious about making sure that new commands or command extensions get documented in config/usage.cfg at a bare minimum, so that useful features can be found and used without relying on word-of-mouth and trial-and-error.
As far as code commenting, I don't see much of a consistent standard, with comments on their own line and comments appended to the end of code-containing lines both being present. It might just be easier to make both permissible (but need to make sure that commenting is present and adequate for new additions). I tend to add a table-of-contents to very large files (usage.cfg at over 1000 lines, editing.cfg at 2300 lines) but this is not an established precedent.
I don't intend to undercut anyone's authority here, but someone has to get the ball rolling or nothing will happen here. This has been something that has been on the "we'll do it "soon" " list for a long time now.
Right now, functions are rarely described with comments which help explain how a block of code works. Adding a preface before functions should help laypeople who wish to contribute figure out what is going on without reading through and deciphering the entire function's code. I propose requiring something like this: https://github.com/red-eclipse/base/blob/9822fd01af4894fe41ee717497eb03cfc28ce269/config/stdlib.cfg#L184-L204 The comments at the beginning are to establish to others:
- what the code does
- what the arguments to feed into the code are
- what the function returns
Hopefully providing these data (which hopefully the person writing the code should know) will help others also understand a codebase which has been complained about in the past on multiple occasions about its opacity.
I wouldnt advise a custom documentation style, use something common: http://www.doxygen.nl/manual/docblocks.html So in case we would be able to generate a documentation.
I wouldnt advise a custom documentation style, use something common: http://www.doxygen.nl/manual/docblocks.html So in case we would be able to generate a documentation.
I agree with the usage of Doxygen here, although I do not know how well it plays with CubeScript.
Nonetheless, I would also like to push for C++ code to be documented properly to encourage engine work/improvements and encourage developers to implement new feature and mechanics to the game.
You may use the format specified above, but using comment blocks instead as C++ supports them (/**/). I would also push for consistent grammar and proper capitalization of words to keep it professional and clean once it gets imported by Doxygen.
Doxygen format looks like it will be OK for Cubescript, using //! or /// for every line instead of multiline block comments (which clearly won't work). I assume that Markdown will be weapon of choice for formatting this infile documentation? If so, there may be additional formatting that should be required beyond capitalization and grammatical correctness (like tables for inputs and outputs perhaps).
Markdown will, indeed, be our weapon of choice.
I believe a Markdown interpreter is already implemented on our website, @shacknetisp confirm
This is a simple command with how I'd document it in C++; is this a documentation style worth keeping, or is there some other idea on how to format it?
/*!
* ### readfile (sb)
* returns specified file as a single string (not as a series of lines in a list; newlines are preserved)
* #### Arguments:
* - file: path to desired file to read
* - msg: toggles readout of file read status (always enabled if `verbose` >=2)
* #### Returns:
* - (as command) string readout of file
* - (as function) true if file sucessfully read; 0 if file not found/unreadable
*/
bool readfile(const char *file, bool *msg)
{
string s;
copystring(s, file);
char *buf = loadfile(s, NULL);
if(!buf)
{
if(msg || verbose >= 2) conoutf("\frCould not read %s", file);
return false;
}
if(msg || verbose >= 2) conoutf("Read %s", file);
commandret->setstr(buf);
return true;
}
COMMAND(0, readfile, "sb");
Markdown rendering:
readfile (sb)
returns specified file as a single string (not as a series of lines in a list; newlines are preserved)
Arguments:
- file: path to desired file to read
- msg: toggles readout of file read status (always enabled if
verbose>=2)
Returns:
- (as command) string readout of file
- (as function) true if file sucessfully read; 0 if file not found/unreadable
I'm not a fan of lines beginning with spaces. I suggest either // - or - /* then ** then */.
Example:
/*!
** ### readfile (sb)
** returns specified file as a single string (not as a series of lines in a list; newlines are preserved)
** #### Arguments:
** - file: path to desired file to read
** - msg: toggles readout of file read status (always enabled if `verbose` >=2)
** #### Returns:
** - (as command) string readout of file
** - (as function) true if file sucessfully read; 0 if file not found/unreadable
*/
@graphitemaster proposed the following, with some modest changes to formatting:
/**
** ### readfile(`file`: *string*, `msg`: *bool*)
** returns specified file as a single string (not as a series of lines in a list; newlines are preserved)
** #### Parameters:
** - `file`: *string* path to desired file to read
** - `msg`: *bool* toggles readout of file read status (always enabled if `verbose` >=2)
** #### Returns:
** - (as command) string readout of file
** - (as function) true if file sucessfully read; 0 if file not found/unreadable
*/
readfile(file: string, msg: bool)
returns specified file as a single string (not as a series of lines in a list; newlines are preserved)
Parameters:
-
file: string path to desired file to read -
msg: bool toggles readout of file read status (always enabled ifverbose>=2)
Returns:
- (as command) string readout of file
- (as function) true if file sucessfully read; 0 if file not found/unreadable