|
|
|
Home » Developing U++ » U++ Developers corner » is there U++ coding style reference?
|
|
| Re: is there U++ coding style reference? [message #27630 is a reply to message #27627] |
Tue, 27 July 2010 00:16   |
|
|
| kohait00 wrote on Mon, 26 July 2010 23:01 |
hi people,
often i read here and there 'your package should comply with U++ coding style'.
does any coding style references exist where one could lookup things? or do we need to bring together stuff?
cheers
|
Hi kohait,
There is no explicit document about coding style, but you can take the U++ sources as reference. Or equivalently the code formating in theide (Edit > Advanced > Format code in editor). I guess that pretty much defines the recommended style. Plus the fact that the functions should be have an uppercase on the word boundaries (including the beginning) and that the code should be clean without unnecessary comments 
That's about it I think, or did I forget something?
Best regards,
Honza
|
|
|
|
|
|
| Re: is there U++ coding style reference? [message #27635 is a reply to message #27632] |
Tue, 27 July 2010 11:06 |
|
|
| kohait00 wrote on Tue, 27 July 2010 08:19 |
thanls dolik
what about indention, tabs / spaces?
brackets on new line?
class definition style, ctor/dtor position (often seen at bottom of cpp or h file, why?)
slight programming guide on when and how to properly design class (virtual dtor etc..) i know this depends on one's own skills as well, but a checklist would help for starters.
cheers
|
You really want a lot of details I usually don't even think about
Prefered indentation is using tabs (better recognized in theide).
Brackets are mostly on the same line. The only exception I can think of is in function definitions.
One important thing is putting spaces around operators etc. It increases the readability a lot.
I'm not sure if there is anything specific about classes, only the fact that U++ mostly uses single header per package and one cpp for each class (or group of closely related classes). I don't know about the ctor/dtor positions, but I strongly prefer having them on top of file, because they ussually contain important info (e.g. callback bindings to widgets).
The programming style is even harder to descrribe The main point would be probably that new and delete should be hidden in implementation, not exposed used in user interface and pointers are used just to point to things. The rest are ussual things, like effective but readable code, reusable classes etc.
Any other ideas? Anybody?
Honza
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Re: is there U++ coding style reference? [message #27675 is a reply to message #27643] |
Thu, 29 July 2010 10:10 |
 |
koldo
Messages: 3357
Registered: August 2008
|
Senior Veteran |
|
|
Some more advices
- Include package files using "Insert package directory file" mainly, instead of using "Insert any file".
- In the second case, tend to use relative to package directory file paths instead of absolute paths.
- If you use Bazaar package, include it to Assembly doing this: "File/Set Main Package", "Assembly" area, right button, "Edit assembly..." option, "Package nests:" field, adding the absolute path to Bazaar at the end.
- Include relative paths instead of absolute in #includes, like #include <Scatter/Scatter.h> instead of #include "/folderA/folderB/Scatter.h"
Best regards
Iñaki
|
|
|
|
|
|
|
|
|
|
| Re: is there U++ coding style reference? [message #27745 is a reply to message #27738] |
Sat, 31 July 2010 22:07 |
|
|
| mdelfede wrote on Sat, 31 July 2010 00:05 |
| dolik.rce wrote on Tue, 27 July 2010 00:16 |
..........
and that the code should be clean without unnecessary comments
|
The point there is to define what's "unnecessary" and how many years you'd like to remember what your code do without having to re-examine it for a week...... I'm still thinking that over-commenting is better than under-commenting.
Same discussion in as wine development. "No unnecessary comments", than just a bunch of people (4-5, I guess, among hundreds of wine contributors) can understand what the hell is happening inside gdi core code. Bah.
Max
|
Hi Max!
Proper documentation does not have to be written as comments. Theide is actually very good at it. The topic++ system let's you describe each functions inputs, outputs and also how it works in "reference" section of documentation, which can be swiftly shown in code editor just by moving the mouse pointer to the squares on the left side gutter. Wider ideas and concepts should be in "implementation" section and end user manuals in "app" section.
I am well aware that writing documentation this way is not as simple and fast as just typing the comments into the code. But I prefer the little extra work if it keeps the code clean.
Also, well named functions and a good structured code can make wonders 
That said, I agree that non-documented code that is not understandable to anyone is useless. I just wanted to point out that there is more than one way to do it
Best regards,
Honza
|
|
|
|
| Re: is there U++ coding style reference? [message #27748 is a reply to message #27745] |
Sat, 31 July 2010 23:00 |
mdelfede
Messages: 1307
Registered: September 2007
|
Ultimate Contributor |
|
|
| dolik.rce wrote on Sat, 31 July 2010 22:07 |
Hi Max!
Proper documentation does not have to be written as comments. Theide is actually very good at it. The topic++ system let's you describe each functions inputs, outputs and also how it works in "reference" section of documentation, which can be swiftly shown in code editor just by moving the mouse pointer to the squares on the left side gutter. Wider ideas and concepts should be in "implementation" section and end user manuals in "app" section.
I am well aware that writing documentation this way is not as simple and fast as just typing the comments into the code. But I prefer the little extra work if it keeps the code clean.
Also, well named functions and a good structured code can make wonders
That said, I agree that non-documented code that is not understandable to anyone is useless. I just wanted to point out that there is more than one way to do it
Best regards,
Honza
|
Hi Honza,
well, I didn't mean that comments should be like that one :
// increment i by one
i++;
But, when you read this :
#endif
Vector<Scroll> scroll;
VectorMap<Ctrl *, MoveCtrl> move;
VectorMap<Ctrl *, MoveCtrl> scroll_move;
Ptr<Ctrl> owner;
};
Top *top;
you surely agree that :
1) You can't have the minimal clue of understanding what the hell 'top' variable means, without reading 3/4 of CtrlCore code
2) You have no hint either of what are move and scroll_move members
and so on.
Nor you'll find them in TPP topics, because they're mostly private members non accessible from external code, so no use on document them in public TPP files.
BUT, if you have to add something to CtrlCore code, fix some bug or simply try to understand the code you're quickly in a trouble.
You can't either have a clue of what Top is looking at its definition :
struct Top {
#ifdef PLATFORM_WIN32
HWND hwnd;
UDropTarget *dndtgt;
#endif
#ifdef PLATFORM_X11
Window window;
#endif
Vector<Scroll> scroll;
VectorMap<Ctrl *, MoveCtrl> move;
VectorMap<Ctrl *, MoveCtrl> scroll_move;
Ptr<Ctrl> owner;
};
So, when I say "better overcommenting than undercommenting" I mean exactly that.
A couple of years ago I had to put my hands in CtrlCore code to add X11DHctrl (and so X11 GlCtrl), ant this costed me a lot of work just to figure out what 'Top' was used for, among other stuffs. And, the bad stuff is that NOW (after a couple of years) I completely forgot all the implications of touching at it so, If should put my hands again on it I'd have to redo all the work from beginning.
So, I guess that (IIRC, of course....) putting something like that :
// top : pointer to underlying native window, if the control is native, NULL otherwise
Top top;
would have spared me some work at the expense of a short comment line. Worse than that, before the X11DHCtrl control (so, when I had to write it...) 'top' variable was unioned with another var in order to spare some memory; on non-native controls the top was NOT null but had another (IIRC completely unrelated) meaning.
If you look ad wine core graphics code, you'll find tons of these examples, and I defy you to manage to understand what's going on without loosing some months to go through all code and without tons of trials-and-errors patching it.....
Purpose of commenting code is *not* to document it from the user's point of view, but making it quickly readable from developer's point of view, even many years later.
Max
|
|
|
|
| Re: is there U++ coding style reference? [message #27760 is a reply to message #27748] |
Mon, 02 August 2010 09:06 |
 |
kohait00
Messages: 939
Registered: July 2009
Location: Germany
|
Experienced Contributor |
|
|
hey mdelfede,
your point id pretty clear. i myself tend to 'overcomment' things as well. but the problem often is, that the commments are quite cryptic anyway. so even I myself, after several months have to really think about 'what did I mean with the comment' .
so the problem is not only to know 'where' to put some commentary hints, but also the 'what' to put there and how detailed. too little and you could have spared it, too much and it makes you think about just as much as if there were no comments.
so the clue on all that is to figure out 'the grain of information' which is needed later.
concerning upp code itself, i admit, i was (and still am) a beginner in a lot of programming topics, but i really learned MUCH from perceptable Upp coding style.though the code is mostely ot commented at all, it can be read qquite well. the quite offensive promotion of 'smart and agressive use of C++' is not underestimated and is a truth. but on the other hand ofcorse, i am very thankful for the forum, becasue there are fields where comments would just save some truble.
to comlete some coding style again:
often, one does not need to know every variable and its usage. the 'big picture' is often the best starting point for own development. these 'presumptions' taken by the programmer and author of the class / code are the missing stone, i.e. in Map Containers in upp, the approach is to simply have the desired container with an Index<> of the keys aligned to the same size and corresponding in indices. this makes further searches a lot easier because one can recognize more in the code. nevertheless, a prgrammer will not spare the work to dig the code a bit, if wanting to provide some new functionality or patch. but the step to go there can vary in extent, this is for sure, with the amount of quality information available on the subject don't underestimate simply visual reading of code.
another thing i personally really like about upp is the tendency to use really short but intuitive variables and even members. this makes the code itself less 'typographic' and enables focusing on the algorithm instead of literal text . especially things like '_myMember' or 'm_myOtherWeiredMember' make life unnesseccarily hard (with the help of Assist++ (STRG+Space) one esealy can find out if it's a member anyway).
good is also, that there is kind of a standard implicit positive action in many API functions, to be used as triggers or parameters or so, and they have negative counterparts that simply rely on the positive ones.
void Enable(bool e = true) {/*your code*/
void Disable() { return Enable(false); }
bool IsEnabled() const { /*your code*/ }
is really practical.
that was my 2 cents
|
|
|
|
|
|
| Re: is there U++ coding style reference? [message #27763 is a reply to message #27761] |
Mon, 02 August 2010 11:39 |
|
kohait00
Messages: 939
Registered: July 2009
Location: Germany
|
Experienced Contributor |
|
|
regarding function names and variables:
Upp makes a lot usage of implicit semantic (already mentioned above) i,j,k are interger counter variables (even have abreviations for it), s is mostly a temporary string, b is bool etc..
this is not hungarian style (as to quote Linus: "hungarian is braindamaged"). in times of Assist++ and other helpers one can safely burry this idea.
this is implicit usage makes really slim synataxes possible. i.e. if(b) { //foo }, which really adds to readability.
the function names just names, they really define the action that is expected. good example are the containers, Add(), Remove(), Detach(), short, readable, general. general is also really important. this is a major advantage of upp code style. the functions exposed are not too specialised but rather imply and use typical knowledge of operation (containers again good example).
the style used for the function names is Pascal Case (according to wiki . starting with capital letter and compunding each word again with its capital letter.
|
|
|
|
|
|
|
|
Goto Forum:
Current Time: Wed Apr 24 16:31:45 CEST 2024
Total time taken to generate the page: 0.03230 seconds
|
|
|
Members
Pages
Help
Register
Login
Home
