2.9 KiB
2.9 KiB
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.