Comments (14)
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.
from base.
from base.
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.
from base.
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 :)
from base.
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.
from base.
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.
from base.
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.
from base.
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.
from base.
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).
from base.
Markdown will, indeed, be our weapon of choice.
I believe a Markdown interpreter is already implemented on our website, @shacknetisp confirm
from base.
yes, https://github.com/red-eclipse/red-eclipse.github.io
from base.
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
from base.
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
*/
from base.
@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 readmsg
: 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
from base.
Related Issues (20)
- Zapper Vars
- [BUGBOT][Game logic] Issues with Authentication Connection and Client Disconnections
- [BUGBOT][Game logic] Implement Pattern Support for Weapon Rays Spacing
- [BUGBOT][Game logic] Introduction of a Non-Explosive Minigun Weapon
- [BUGBOT][Graphics] Investigate Waterfall Dynamics for Enhancing Volumetric Fog Material HOT 1
- [BUGBOT][UI] Add vertical movement keys in editor without changing orientation
- [BUGBOT][Game logic] Claw Secondary Action Not Functioning
- [BUGBOT][Graphics] Gradual Increase in VRAM Usage Over Time
- [BUGBOT][UI] Mismatch in Player Model Gender Settings HOT 1
- [BUGBOT][Game logic] Server-side variable changes display incorrect previous values HOT 1
- [BUGBOT][Game logic] Lack of Priority System for Picking Up Stacked Items in Matches
- [BUGBOT][Sound] Announcer Repeatedly Spams 'FIGHT!' at Start of Duel Game Mode
- [BUGBOT][Game logic] Implementing Guided Prize Targeting System
- [BUGBOT][UI] New Maps and Demos Not Visible Without Restarting Game Due to Caching Issue
- Add server var for MOTD popup ui
- [BUGBOT][UI] Enhance scoreboard visibility for dead players
- [BUGBOT][Graphics] Ticker Texture Display and Distortion Issue
- [BUGBOT][UI] Improvements to Compass Usability and Design
- Bullet Shell Model
- [BUGBOT][UI] Lack of functionality to save UI-generated composites to disk
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from base.