Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Ticket #16 (closed task: fixed)

Opened 18 years ago

Last modified 18 years ago

Complete coding conventions document

Reported by: larsivi Assigned to: kris
Priority: major Milestone: 0.7
Component: Tango Version:
Keywords: Cc:

Description

This is a more high level document than the one asked for in #15.

Current notes:

  • Common license: BSD
  • Selecting viable projects & portions thereof:
    • Ares
    • Mango
    • DDL
    • Build
    • ?
  • Suggested documentation conventions
    • License at top of file, along with author names, copyright text, revision list, etc.
    • Along with functions and methods, each struct, class, interface, or other aggregate should have some descriptive annotation. Each of these represent a good place to add short usage examples, using the ddoc "---" mechanism.
    • Ensure that only the expected interface is exposed by the API documentation.
    • Document each non-private enum-member, such that it will be included in the API documentation.
  • Suggested coding conventions
    • Use CamelCase for Module names. This permits more flexibility in descriptive naming, which is an important aspect of good documentation.
    • Capitalize, or use CamelCase for all aggregate-types and for enum member-names.
    • Use the "override" keyword appropriately. This will help make the code more robust in the face of long-term changes.
    • The default visibility of methods, attributes, members, enums, structs etc, should be private. Expose only what's necessary.
    • Make all imports private by default. Consider exposing those which would be required to invoke the primary function of the given module; such as the arguments to public class constructors. This makes trivial usage simple, yet helps to reduce namespace collisions and actually makes the compiler run faster (nice side-effect).
    • When using default argument values, try to order them such that common usage has the least knowledge required
    • Avoid large numbers of parameters (6 and above?) where at all possible. If things start to get crazy, consider using a struct to gather related arguments instead.
    • Consider returning a value from all methods/functions. It's almost free! Call-chaining is one reasonable application of this idiom.
    • Please, please, please use spaces instead of tabs ;)
  • Possible extras:
    • Common code style (long term?)

Change History

06/28/06 17:09:15 changed by kris

  • status changed from new to closed.
  • resolution set to fixed.

We now have a CodingConventions wiki page

Roadmap Timeline Tickets New Ticket Help / Guide About Trac
Login  |  
Trac dsource.org
RSS
Copyright © 2006-2024 Tango. All Rights Reserved. | Page Width: Static or Dynamic