-
-
Notifications
You must be signed in to change notification settings - Fork 86
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Coding style? #49
Comments
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. |
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:
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:
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 |
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 ( |
Doxygen format looks like it will be OK for Cubescript, using |
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?
Markdown rendering:readfile (sb)returns specified file as a single string (not as a series of lines in a list; newlines are preserved) Arguments:
Returns:
|
I'm not a fan of lines beginning with spaces. I suggest either Example:
|
@graphitemaster proposed the following, with some modest changes to formatting:
readfile(
|
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.The text was updated successfully, but these errors were encountered: