#### Introduction
Test automation consists of two types of software project: The tool or utility application, and the test suite. Each has its own context and purpose. Worse yet, each programming language has built up around it, a set of standards and practices that are unique to that language. Because we work with two different development languages, this requires us to maintain not two, but four different documentation / and code commentary standards. For the sake of brevity, the list of conventions that are common to both will be aggregated into a single set of general conventions for both languages.

#### Definitions
-   __Documentation:__ written material that provides official information or evidence or that serves as a record of a subject.
-   __Comments:__ human readable annotations in source code, intended to improve the readability of or clarify the code itself.
-   __Documentation comments:__ Annotations in source code that are meant to be parsed by a document generator, intended to function as human readable documentation.

#### General Conventions

__Comments__

    DO: Keep them short. 80 Characters or less is ideal, though slightly longer may be tolerable. If you're writing a short story, maybe you need to rethink your code.
    DO: Make them informative. If your comment cannot answer a "why" question, it's probably not needed, or you need to rethink your code.
    DO: Keep them current and relevant. If this is a TODO comment, include a link to the JIRA ticket for it. If the work is done, remove it.

    DON'T: Restate your method name in english. //Get Current Record ID is not a comment. It's a method name.
    DON'T: Describe the functionality. If I can't figure out what the code is doing, either the method needs rewriting, or I need to educate myself.
    DON'T: Disable code. If there is code that is not needed, unhelpful, or broken, REMOVE the code. If you need to recover it, that's what git is for.

__Documentation__

    DO: Be as concise as possible: While clarity and thoroughness are necessary, this doesn't necessitate writing a book.
    DO: Provide a context, and a goal: under what conditions will I be using this method, and what will I be trying to achieve?
    DO: Describe all functionality: Unlike comments, documentation is DESIGNED for the purpose of description.
    DO: Include examples: where they add to clarity and shorten descriptions, examples can be excellent forms of documentation.

    DON'T: Tell a story. Future readers aren't going to care what happened on a specific day in the life of a library module. That's what release notes and commit histories are for.
    DON'T: Describe intentions or desires: Future readers aren't going to care what you wish the code did or might do in the future. Only what it actually does.
    DON'T: Describe removed or deprecated features: Only describe the officially supported and maintained functionality.