View previous topic :: View next topic |
Author |
Message |
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Fri Jan 06, 2006 3:16 pm Post subject: Coding style |
|
|
I was just thinking that maybe a style document for the code might be a good idea. I always like to have one around, just to have an authorative source.
This is of course prompted by me not liking the extensive use of tabs in DDL I hate em, and avoid whenever possible. It might just be my editor (Kate at the moment), but the current indentation is very large on my system. This is fairly good for clarity, but for deep nestings, this get somewhat bad looking because you need to line wrap most of the code (whether it is done manually or automatically). If I were to choose, I would make indentation two spaces...
As for naming and such, I find it more or less quite good. But having some rules in place, might help. |
|
Back to top |
|
|
pragma
Joined: 28 May 2004 Posts: 607 Location: Washington, DC
|
Posted: Fri Jan 06, 2006 3:44 pm Post subject: |
|
|
I've done my best to adhere to the style outlined on DM, plus a few variations of my own:
http://www.digitalmars.com/d/dstyle.html
The things I try to do that supercede this are:
- Using tabs for indentation instead of spaces: as AgentOrange pointed out, most editors can configure the default tab width. This keeps everyone happy.
- Using a lower-case for package names, and CamelCase for a given module name (like Mango). The module should be named for the dominant class within the module, and or the functional area it supports (in the case of ddl.Utils or ddl.Demangle).
- Use of all.d, where appropriate, to allow for easy inclusion of everything at a given package level.
- Comments should support ddoc, and exploit its features where they support both the generated and in-source readability of the documenation. This especially goes for documenting any known or potential side-effects, failure modes and consequences of overloading for methods.
- Use //TODO: things you plan on doing. This makes searching easy.
- Use //HACK: for code that is likely to be culled out based on its appearance. The comment should be used to justify the hack implemented, and the consequences for removing, refactoring or replacing the code. Also, any dependencies on the behavior/version of other parts of the program (especially if the hack exploits a known bug) should also be documented.
- Place the (short form) of the project license in every source file, and update the authors and copyright year as appropriate.
I think Don might have some suggestions for templates or template coding styles. _________________ -- !Eric.t.Anderton at gmail |
|
Back to top |
|
|
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Fri Jan 06, 2006 3:52 pm Post subject: |
|
|
Don't wish to start a space/tab war, but tabs will always be an issue for someone. Over the years I've found it better to stick with spaces only, by ensuring my editor insert spaces for tabs ~ then there's no confusion, or need for tab re-configuration.
2 Cents only |
|
Back to top |
|
|
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Fri Jan 06, 2006 3:55 pm Post subject: |
|
|
pragma wrote: |
- Using tabs for indentation instead of spaces: as AgentOrange pointed out, most editors can configure the default tab width. This keeps everyone happy.
|
The strangest thing happened, I got two mails indicating replies, but the first pointed to some empty posting (?). Would this be AgentOranges reply?
Anyway, tabs keep everyone happy except me I'm aware that editors are configurable, and I always turn on "turn tabs into spaces" (I learnt to like this style at a previous employer of mine, the guidelines said, if I remember correctly, that usage of tab would be rewarded with a trip behind the barn for fast execution by shotgun. I also think that it might be a Unix/Windows thingy, as it seems Tabs are more accepted among Windows coders?) I'll cope though... And I'll have a lot to "fix" already. |
|
Back to top |
|
|
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Fri Jan 06, 2006 3:56 pm Post subject: |
|
|
kris wrote: | Don't wish to start a space/tab war, but tabs will always be an issue for someone. Over the years I've found it better to stick with spaces only, by ensuring my editor insert spaces for tabs ~ then there's no confusion, or need for tab re-configuration.
2 Cents only |
My hero! |
|
Back to top |
|
|
pragma
Joined: 28 May 2004 Posts: 607 Location: Washington, DC
|
Posted: Fri Jan 06, 2006 4:04 pm Post subject: |
|
|
I'd like to get a few more opinions in here on the matter, but I'm more than happy to yield to needs and (especially) wisdom that exceeds my own understanding of things. Besides, I used to be a spacer myself, so I'm not beholden to any particular technique - its just where I am right now.
Besides, its easy enough to go back and forth via a custom util or something.
Suppose that we go with spaces: can we setlle on 4 spaces as a compromise?
Lars: does your editor have any issues coping with windows-style newlines? _________________ -- !Eric.t.Anderton at gmail |
|
Back to top |
|
|
sean
Joined: 24 Jun 2004 Posts: 609 Location: Bay Area, CA
|
Posted: Fri Jan 06, 2006 4:06 pm Post subject: |
|
|
kris wrote: | Don't wish to start a space/tab war, but tabs will always be an issue for someone. Over the years I've found it better to stick with spaces only, by ensuring my editor insert spaces for tabs ~ then there's no confusion, or need for tab re-configuration. |
I've long since given up on tabs as the work of the devil, or at least a minor demon of nonproductivity. Spaces are where it's at. I prefer 4 spaces per tab, but that's something few people agree on |
|
Back to top |
|
|
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Fri Jan 06, 2006 4:12 pm Post subject: |
|
|
pragma wrote: |
Suppose that we go with spaces: can we setlle on 4 spaces as a compromise?
|
Sure, a multiple of two is better than the 3 I found in one project.
pragma wrote: |
Lars: does your editor have any issues coping with windows-style newlines? |
Nope, and if I have, I turn on automatic conversion At least Emacs has a very nifty shortcut.
Note that my biggest gripes with previous projects, has been when there has been either no coding style in the project (or it hasn't been enforced), or my editor haven't supported several "profiles". |
|
Back to top |
|
|
AgentOrange
Joined: 21 Jul 2005 Posts: 61
|
Posted: Fri Jan 06, 2006 4:13 pm Post subject: |
|
|
larsivi wrote: | pragma wrote: |
- Using tabs for indentation instead of spaces: as AgentOrange pointed out, most editors can configure the default tab width. This keeps everyone happy.
|
The strangest thing happened, I got two mails indicating replies, but the first pointed to some empty posting (?). Would this be AgentOranges reply?
Anyway, tabs keep everyone happy except me I'm aware that editors are configurable, and I always turn on "turn tabs into spaces" (I learnt to like this style at a previous employer of mine, the guidelines said, if I remember correctly, that usage of tab would be rewarded with a trip behind the barn for fast execution by shotgun. I also think that it might be a Unix/Windows thingy, as it seems Tabs are more accepted among Windows coders?) I'll cope though... And I'll have a lot to "fix" already. |
I just said set your tabs to two spaces but i deleted it because it really makes no difference to me. I just havent had problems with tabs for years and didnt realize it still gave people issues.... |
|
Back to top |
|
|
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Fri Jan 06, 2006 4:31 pm Post subject: |
|
|
sean wrote: | I've long since given up on tabs as the work of the devil, or at least a minor demon of nonproductivity. Spaces are where it's at. I prefer 4 spaces per tab, but that's something few people agree on |
Amen, brother Sean
Personally, I use AoB (Alignment on Brackets), which is a variable spacing convention that looks really nice and clean. But, I've never seen anyone else use it (perhaps it seems like too much effort). |
|
Back to top |
|
|
JJR
Joined: 22 Feb 2004 Posts: 1104
|
Posted: Fri Jan 06, 2006 9:21 pm Post subject: |
|
|
I've used multiple editors on multiple OSes for programming and editing D code. I've had nothing but frustrations with tabs when changing between systems. Yes, they can be changed in each editor, but doing so still constitutes an annoyance.
After awhile, I settled on tab character and 4 spaces per tabs. I haven't looked back. Using these settings basically removes all possibility of ill effects.
I can see people having no trouble with the tab character, but I'm guessing those are people that have settled on one editor for their programming tasks.
-JJR |
|
Back to top |
|
|
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Sat Jan 07, 2006 4:16 am Post subject: |
|
|
Heh, I got myself a discussion
JJR wrote: |
I can see people having no trouble with the tab character, but I'm guessing those are people that have settled on one editor for their programming tasks.
-JJR |
I have to agree. The biggest gripes for me is when switching between projects having different setups, and switching between editors (because some projects require a certain editor/IDE, or because the editors don't work the same on Windows/Linux). Depending on the feelings of the project leader, there is also huge differences between the enforcement levels. The enforcment can be automatic if one is able to standardize on an editor, though, (Which I suppose is totally out of the question , as e.g. Vim can read such settings from embedded comments in the sources. I |
|
Back to top |
|
|
JJR
Joined: 22 Feb 2004 Posts: 1104
|
Posted: Sat Jan 07, 2006 5:19 am Post subject: |
|
|
JJR wrote: | After awhile, I settled on tab character and 4 spaces per tabs. I haven't looked back. Using these settings basically removes all possibility of ill effects. |
Arrgggh!!! I actually meant to say "NO tab character" and 4 spaces per tab.
How frustrating to write the opposite!
-JJR |
|
Back to top |
|
|
csauls
Joined: 27 Mar 2004 Posts: 278
|
Posted: Sat Jan 07, 2006 1:51 pm Post subject: |
|
|
I'm with lars on liking to have a standard coding style (heck, when we started Sinbad, wasn't a code stylesheet the very first thing we did?!... wish I could find the darn thing, though). My style with D has changed several times over the last couple of years though... I've finally settled on something but I don't know if many other people would care for it.
And frankly Kris, your style confuses me sometimes... I agree it has a clean look to it, but somehow my brain trips over it sometimes. I guess I just don't like seeing code on the same column as its braces?
As for tabs... I go with no tab character, and two spaces, for most things. (aka, in D) For some platforms (things like markup) I go with four spaces, just for more visual cue. _________________ Chris Nicholson-Sauls |
|
Back to top |
|
|
Don Clugston
Joined: 05 Oct 2005 Posts: 91 Location: Germany (expat Australian)
|
Posted: Mon Jan 09, 2006 12:56 am Post subject: Brace placement - catalogue of options |
|
|
I know there are lots of reglious wars about brace placement. I don't want to get into that, but I think it would be helpful to agree on names and minimal descriptions of the styles. This could be put in the D wiki, perhaps.
As far as I can tell: Walter uses BSD style. kris uses AoB. pragma uses Eckel style. Currently I use Java style, although I've used others in the past.
Any other major ones I've missed? Are there better names for them? Or maybe there's a website out there which already has such a list?
Decisions:
* Position of opening brace.
(a) on new line (BSD style)
(b) on end of previous line (Eckel, Java style).
(c) indented to the block level.
(c) hybrids.
* What happens with else ?
Another orthogonal decision:
* Where are the spaces with for, if, etc.
eg:
(a) if (x==2) { return 3; }
(b1) if( x==2 ) { return 3; }
(b2) if( x==2 ) { return(3); }
I've only ever seen (b) used with BSD style.
---------------------------------
BSD or Allman style (I don't know where that name comes from).
class A
{
int func (int x)
{
if (x==2)
{
return x*3;
}
else
{
return x*4;
}
}
}
Stroustrup (http://public.research.att.com/~bs/bs_faq2.html)
Functions are on a line by themselves
class A {
int func (int x)
{
if (x==2) {
return x*3;
}
else {
return x*4;
}
}
}
-------------
Java (http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html)
class A {
int func (int x) {
if (x==2) {
return x*3;
} else {
return x*4;
}
}
}
-------------
Eckel (http://www.camtp.uni-mb.si/books/Thinking-in-C++/TIC2Vone-distribution/html/AppendixA.html)
class A {
int func (int x) {
if (x==2) {
return x*3;
}
else {
return x*4;
}
}
}
-------------
Is this Alignment on Brackets (AoB)?
class A
{
int func (int x)
{
if (x==2)
{
return x*3;
}
else
{
return x*4;
}
}
}
--------------
Pig's Breakfast
Different every time.
class A
{
int func (int x) {
if (x==2)
{
return x*3;
}
else { return( x*4 ); }
}
} |
|
Back to top |
|
|
|
|
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum
|
Powered by phpBB © 2001, 2005 phpBB Group
|