View previous topic :: View next topic |
Author |
Message |
pragma
Joined: 28 May 2004 Posts: 607 Location: Washington, DC
|
Posted: Thu Aug 26, 2004 7:07 pm Post subject: Open Call for Suggestions: Coding Standards |
|
|
This topic needs no introduction.
What coding standards should we use to keep the entire library coherent?
Thank you for your contributions. _________________ -- !Eric.t.Anderton at gmail |
|
Back to top |
|
|
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Thu Aug 26, 2004 7:29 pm Post subject: |
|
|
documentation, please! A clear and consistent copyright at the top (BSD style?), a description of what each class does, and what each method does. Should be extractable by doxygen. Author(s) and date(s) are useful. Nice-to-have includes method argument info, return value, and code-examples in the class/method comments.
would be good to have some consistency in the Exceptions used.
All internal imports should be private, unless carefully considered. One notion (that Chris Sauls originally suggested for Mango) is to consider exposing those imports which declare things used as constructor-arguments within that module. Of course, you need to try and make those imports reasonably granular to make that work without causing unwanted pollution. |
|
Back to top |
|
|
pragma
Joined: 28 May 2004 Posts: 607 Location: Washington, DC
|
Posted: Thu Aug 26, 2004 9:15 pm Post subject: |
|
|
Deja Augustine also lended some input over at the DNG.
http://www.digitalmars.com/drn-bin/wwwnews?digitalmars.D/9806
(this is split across both the present open calls to help channel the input a little)
I think that a nice idea might be to form a small "committee" of say 2-4
people, tops, who come up with a library interface standard: a specific
set of codified rules for anything to become a part of the standard
library. Have everything from package/module nomenclature to the
notation of classes, methods and members (CONSTANT, ThisIsAMethod,
thisIsAMember, STDThisIsAClass, thisisalocal, etc...).
_________________ -- !Eric.t.Anderton at gmail |
|
Back to top |
|
|
qbert
Joined: 30 Mar 2004 Posts: 209 Location: Dallas, Texas
|
Posted: Thu Aug 26, 2004 9:16 pm Post subject: |
|
|
kris wrote: | documentation, please! A clear and consistent copyright at the top (BSD style?), a description of what each class does, and what each method does. Should be extractable by doxygen. Author(s) and date(s) are useful. Nice-to-have includes method argument info, return value, and code-examples in the class/method comments.
|
While I agree documentation is important, I don't think doxygen should be required. I personally dont like it, the documentation it produces is horrible to navigate, and not everyone is familiar with its use ( just my vote, not trying to cause waves ).
Also what about naming conveions
class MyClass {
public:
int lowercaseVariable;
void lowercaseMethods ()
}
enum : uint CAPITALENUM {}
etc...
Charlie |
|
Back to top |
|
|
pragma
Joined: 28 May 2004 Posts: 607 Location: Washington, DC
|
Posted: Thu Aug 26, 2004 9:32 pm Post subject: |
|
|
Personally, I'm all for auto-generated document generation, but I'm with qbert on the fact that Doxygen isn't quite at 100? for D. Are there any other tools out there that can generate documentation for D?
I know it sounds perverse to use on D, but has anyone tried JavaDoc at all?
As for an actual coding standard, I'm also in agreement with qbert on his preliminary style suggestion. This looks a lot like the typical Java style, which is what my vote is for.
For those interested:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
I'd like to use the Java Coding Standard, mapped as closely to D as possible. Obviously, this leaves things like enums, aliases, and how many classes to a file, etc to be hammered out. But it' would give us a good head start.
I'm sure there are other ready-to-go coding standards are out there for C++ and other languages, I'm just not familiar with them. _________________ -- !Eric.t.Anderton at gmail |
|
Back to top |
|
|
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Thu Aug 26, 2004 10:27 pm Post subject: |
|
|
I'd like to suggest that classes be split into mutable and non-mutable relatives wherever it makes sense. For example, Having a URI class is all fine and well, but it's actually much more useful (long term) to split it into an immutable Uri base-class, and derive a MutableUri from it. Same goes for a FilePath class, and so on.
Whilst handy in general programming, this becomes invaluable when writing multi-threaded stuff, distributed systems, agent-based systems, or even high-thoughput cache-oriented environments. If you know something can't be changed once it's been constructed, you can usually optimize very effectively. The best thing is that there's really no cost involved in doing so. Anyone who wants a modifiable version simply uses the MutableUri (or whatever) instead, which will be automatically downcast to the immutable base-class as needed.
Perhaps it might be useful to find some links discussing the merits of immutable classes? |
|
Back to top |
|
|
andy
Joined: 15 Mar 2004 Posts: 71
|
Posted: Thu Aug 26, 2004 10:42 pm Post subject: |
|
|
Just to throw an idea out, the .NET naming scheme is quite different from Java, and I don't know if I like it or not, but it's certainly easy to remember:
To paraphrase:
Microsoft wrote: | Everything is PascalCase, except for private attributes and parameters, which can be camelCase. |
_________________ "Complacency is a far more dangerous attitude than outrage." - Naomi Littlebear |
|
Back to top |
|
|
Arcane Jill
Joined: 01 Jun 2004 Posts: 10
|
Posted: Fri Aug 27, 2004 12:42 am Post subject: |
|
|
Kris wrote: | I'd like to suggest that classes be split into mutable and non-mutable relatives wherever it makes sense. |
You mean, like, to compensate for D's total lack of const functionality?
andy wrote: | Just to throw an idea out, the .NET naming scheme is quite different from Java |
D already has a style guide. I suggest we stick to it.
Jill |
|
Back to top |
|
|
kris
Joined: 27 Mar 2004 Posts: 1494 Location: South Pacific
|
Posted: Fri Aug 27, 2004 12:52 am Post subject: |
|
|
Arcane Jill wrote: | Kris wrote: | I'd like to suggest that classes be split into mutable and non-mutable relatives wherever it makes sense. |
You mean, like, to compensate for D's total lack of const functionality?
|
It's actually worth considerably more than that. But you were being sardonic <g> |
|
Back to top |
|
|
sean
Joined: 24 Jun 2004 Posts: 609 Location: Bay Area, CA
|
Posted: Fri Aug 27, 2004 1:09 am Post subject: |
|
|
qbert wrote: |
Also what about naming conveions
|
I suggest we just follow the D style guide. More tomorrow when I've had some sleep |
|
Back to top |
|
|
jcc7
Joined: 22 Feb 2004 Posts: 657 Location: Muskogee, OK, USA
|
Posted: Fri Aug 27, 2004 9:00 am Post subject: |
|
|
Here's some proposed "rules" (partially inspired by the "Project Direction and Features" topic):- Only use OO if it's helpful. This isn't Java. In D, we shouldn't use objects unless it makes sense.
- Only use structs when necessary. Namespace pollution can be avoided by writing concise modules that involve closely related idea.
- Library modules should "private import" other modules unless there's a strong reason for a public import (and that reason should be documented). |
|
Back to top |
|
|
teqdruid
Joined: 11 May 2004 Posts: 390 Location: UMD
|
Posted: Fri Aug 27, 2004 1:48 pm Post subject: |
|
|
Quote: | - Only use OO if it's helpful. This isn't Java. In D, we shouldn't use objects unless it makes sense. |
I disagree, and would revise that to say: use OO by default, use global methods it they're stateless. (is stateless the right terminology?) Basically, use OO unless it's a one-shot thing. In practice this may be the same, since OO is typically very helpful.
Quote: | - Only use structs when necessary. Namespace pollution can be avoided by writing concise modules that involve closely related idea. |
Agreed, but I'm not sure how the two relate.
Quote: | - Library modules should "private import" other modules unless there's a strong reason for a public import (and that reason should be documented). |
Agreed. |
|
Back to top |
|
|
jcc7
Joined: 22 Feb 2004 Posts: 657 Location: Muskogee, OK, USA
|
Posted: Fri Aug 27, 2004 5:24 pm Post subject: |
|
|
demmegod wrote: | Quote: | - Only use OO if it's helpful. This isn't Java. In D, we shouldn't use objects unless it makes sense. |
I disagree, and would revise that to say: use OO by default, use global methods it they're stateless. (is stateless the right terminology?) Basically, use OO unless it's a one-shot thing. In practice this may be the same, since OO is typically very helpful. | Sorry, I was unclear. I think we agree.
I'm not saying we should use never use OO in the library (for exapmple, OO is extremely helpful with streams). I meant that we shouldn't use OO for everything. I shouldn't have to use an object to convert an int to a string. I just call the toString function.
I'll try to articulate it better, next time. |
|
Back to top |
|
|
larsivi Site Admin
Joined: 27 Mar 2004 Posts: 453 Location: Trondheim, Norway
|
Posted: Sat Aug 28, 2004 5:42 am Post subject: |
|
|
I think the styleguide made me and csauls for Sinbad was very good. As it is, the area where it was seems to be gone... Some of the discussions around it can still be found here
http://www.dsource.org/forums/viewtopic.php?t=75
though. |
|
Back to top |
|
|
saivert
Joined: 15 Aug 2005 Posts: 8 Location: Norway
|
Posted: Wed Aug 17, 2005 3:16 pm Post subject: module names and locations |
|
|
Another nice thing would be to decide on where on your PC the various modules should be installed and how to name modules and packages.
Currently the Core32 (a nice set of Win32 headers for D) package have been spotted in two different locations:
1. c:\dmd\src\core32
2. c:\d\import\core32
I use option #1 as phobos is also in dmd\src folder and Ares will be there too (at least on my system).
And some just copy files withing the core32\win32 folder (in the ZIP) to to a core32 folder so you must do:
import core32.api;
while:
import win32.api;
is more descriptive.
I think most peolpe use sc.ini (from dmd\bin) to set the import roots (aka include path) instead of using -I arguments or environment variables.
While this has nothing to do with code it is an important part when WORKING with code as a standard way to keep files make it easier when multiple people work on the same project. _________________ - New at D, like it though - Attending Kongsberg Tekniske Fagskole (Computer technician course) - |
|
Back to top |
|
|
|