FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

Open Call for Suggestions: Coding Standards
Goto page 1, 2, 3  Next
 
Post new topic   Reply to topic     Forum Index -> Ares
View previous topic :: View next topic  
Author Message
pragma



Joined: 28 May 2004
Posts: 607
Location: Washington, DC

PostPosted: Thu Aug 26, 2004 7:07 pm    Post subject: Open Call for Suggestions: Coding Standards Reply with quote

This topic needs no introduction.

Question 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
View user's profile Send private message Yahoo Messenger
kris



Joined: 27 Mar 2004
Posts: 1494
Location: South Pacific

PostPosted: Thu Aug 26, 2004 7:29 pm    Post subject: Reply with quote

Exclamation 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.

Idea would be good to have some consistency in the Exceptions used.

Idea 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
View user's profile Send private message
pragma



Joined: 28 May 2004
Posts: 607
Location: Washington, DC

PostPosted: Thu Aug 26, 2004 9:15 pm    Post subject: Reply with quote

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
View user's profile Send private message Yahoo Messenger
qbert



Joined: 30 Mar 2004
Posts: 209
Location: Dallas, Texas

PostPosted: Thu Aug 26, 2004 9:16 pm    Post subject: Reply with quote

kris wrote:
Exclamation 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 Confused ).

Also what about naming conveions

class MyClass {
public:
int lowercaseVariable;

void lowercaseMethods ()

}

enum : uint CAPITALENUM {}

etc...

Charlie
Back to top
View user's profile Send private message MSN Messenger
pragma



Joined: 28 May 2004
Posts: 607
Location: Washington, DC

PostPosted: Thu Aug 26, 2004 9:32 pm    Post subject: Reply with quote

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.

Arrow For those interested:
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html

Idea 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. Sad
_________________
-- !Eric.t.Anderton at gmail
Back to top
View user's profile Send private message Yahoo Messenger
kris



Joined: 27 Mar 2004
Posts: 1494
Location: South Pacific

PostPosted: Thu Aug 26, 2004 10:27 pm    Post subject: Reply with quote

Idea 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
View user's profile Send private message
andy



Joined: 15 Mar 2004
Posts: 71

PostPosted: Thu Aug 26, 2004 10:42 pm    Post subject: Reply with quote

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
View user's profile Send private message
Arcane Jill



Joined: 01 Jun 2004
Posts: 10

PostPosted: Fri Aug 27, 2004 12:42 am    Post subject: Reply with quote

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
View user's profile Send private message
kris



Joined: 27 Mar 2004
Posts: 1494
Location: South Pacific

PostPosted: Fri Aug 27, 2004 12:52 am    Post subject: Reply with quote

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?

Twisted Evil
It's actually worth considerably more than that. But you were being sardonic <g>
Back to top
View user's profile Send private message
sean



Joined: 24 Jun 2004
Posts: 609
Location: Bay Area, CA

PostPosted: Fri Aug 27, 2004 1:09 am    Post subject: Reply with quote

qbert wrote:

Also what about naming conveions

I suggest we just follow the D style guide. More tomorrow when I've had some sleep Smile
Back to top
View user's profile Send private message
jcc7



Joined: 22 Feb 2004
Posts: 657
Location: Muskogee, OK, USA

PostPosted: Fri Aug 27, 2004 9:00 am    Post subject: Reply with quote

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
View user's profile Send private message AIM Address
teqdruid



Joined: 11 May 2004
Posts: 390
Location: UMD

PostPosted: Fri Aug 27, 2004 1:48 pm    Post subject: Reply with quote

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
View user's profile Send private message Send e-mail AIM Address
jcc7



Joined: 22 Feb 2004
Posts: 657
Location: Muskogee, OK, USA

PostPosted: Fri Aug 27, 2004 5:24 pm    Post subject: Reply with quote

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. Smile
Back to top
View user's profile Send private message AIM Address
larsivi
Site Admin


Joined: 27 Mar 2004
Posts: 453
Location: Trondheim, Norway

PostPosted: Sat Aug 28, 2004 5:42 am    Post subject: Reply with quote

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
View user's profile Send private message
saivert



Joined: 15 Aug 2005
Posts: 8
Location: Norway

PostPosted: Wed Aug 17, 2005 3:16 pm    Post subject: module names and locations Reply with quote

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
View user's profile Send private message MSN Messenger
Display posts from previous:   
Post new topic   Reply to topic     Forum Index -> Ares All times are GMT - 6 Hours
Goto page 1, 2, 3  Next
Page 1 of 3

 
Jump to:  
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