Where to document the coding decisions?

Question

While creating an application there are decisions we make, like the naming or calling conventions, format of data etc.

Where should I document this? Options:

1. Within the code, at the top.

2. Within the code, where such decision are being effected, e.g. declaring variables, defining functions etc.

3. Separate document.

The list is not exhaustive.

Answer 1

We use a separate Coding Guidelines document that all developers are required to read with an eye for understanding and improving the guidelines.

Answer 2

It can be good to use a separate wiki (or similar project collaboration software) for documentation (and discussion thereof) that is written during development and shared among the developers, such as road maps, etc.

The software you use for bug tracking is also likely to end up containing much of the discussion around decisions taken in the project. It is ideal for 'things you are going to implement/change/do' about the project.

(If you can get a bug tracking/project collaboration style software that does both, half your luck!)

I don't believe that naming or calling conventions need to or should go within the code. For a start, your code is probably hundreds of source files, so it's unclear where it would go. Good question though, maybe others have different opinions.

Answer 3

I think the best documentation is inline, i.e. within the code. When you document your code in a separate document, it's difficult to keep it fresh. And inline documentation is always relevant

Answer 4

It depends on the scope of the decision that was made. Generally things like naming conventions are going to be company-wide (or at least language-wide if you use multiple languages), and should therefore be stored in company-wide documentation.

High-level design decisions, even if made after the formal design phase, should be documented alongside the usual design documentation.

Low-level coding decisions (such as choosing a linked list over an array) can be left in code documentation, unless it's a significant low-level decision.

Format of data can be low-level, high-level, company-wide or even extra-company in scope. It depends on what the data is for. If it's just a log file format, leave it in the code. If it's a company-mandated format, document it at that level.

The bottom line is document decisions at the highest level where they are appropriate, but not higher.

Answer 5

For things such as naming conventions, white space, etc create a coding standards document. For high level things specific to the design of your project such as database schema document information in design documents or use a Wiki so everyone can easily update info. Only document things specific to a certain section of code in your source file, for example using a certain function or data structure for performance reasons.

Answer 6

In my human-computer interaction course text (section about software engineering) there's a section which talks about "Design Rationale", a technique to document:

• What is the rationale behind a certain decision.
• Which alternatives have been explored.
• What was the context of the decision.

I think that's what you're talking about, there are several frameworks for design rationale, and they are also linked on the design rationale wikipedia article.