Coding Standards Research Paper

On By In 1

The Insights Association is in the process of developing a new Code of Standards. To be published later this year, it will incorporate elements of both the CASRO and MRA Codes. In addition, it will reflect important recent developments in research and analytics technology and technique. Until the new Code is published, the CASRO Code continues to apply to Insights Association company members and the MRA Code will apply to individual members. If you have specific questions about the Codes, please contact us.

DOWNLOAD PDF OF CODE

Introduction

CASRO is the national association established in 1975 to represent the U.S. research industry and those organizations engaged in the conduct, support, or education of market, opinion, and social research, often described as data analytics, consumer insights, or business intelligence. CASRO’s member organizations, which reflect about 85% of U.S. annual research revenues, are represented in CASRO by the Chief Executives and other corporate officers, serving on CASRO’s Board and leading CASRO’s initiatives and events. CASRO’s mission is to provide the environment and leadership that will advance the integrity, quality, and best interests of research businesses, as well as the U.S. and global research industry. CASRO advances the business of research through mandatory and enforceable standards, guidance and guidelines, education and information resources, and self-regulation in research process, practice, and performance. CASRO works with national and international associations to support and improve the integrity and quality of research across geographic and cultural borders. This Code of Standards and Ethics for market, opinion, and social research sets forth the agreed-upon rules of ethical conduct for research organizations. Acceptance of this Code is mandatory for all CASRO members, and Code Enforcement Procedures are available to address any complaints and alleged breaches of the Code. The Code has been organized into sections describing the responsibilities of a research organization to research participants (also called "respondents” or "data subjects”), to research clients, to subcontractors, and to interviewers; as well as the responsibilities of organizations in reporting research project results. This Code is not intended to be, nor is it, an immutable document. Circumstances may arise that are not covered by this Code or that may call for modification of some aspect of this Code. The Standards Committee and the Board of Directors of CASRO will evaluate these circumstances as they arise and, if appropriate, revise the Code. The Code, therefore, is a living document that seeks to be responsive to the changing world of research, while setting forth important principles that should inform the judgment and behavior of research organizations based on the ethical spirit of the code, even in circumstances for which definitive standards have not been updated or articulated. In this spirit, CASRO advocates ongoing communication among members, research participants, clients, subcontractors, consultants and interviewers.

The Principles of Market, Opinion, and Social Research

Market, opinion, and social research is an information gathering and analytical activity distinct from marketing and advertising. The following Principles define the research industry and support its unique and critical separation from the societies, industries, and economies that it serves. These research principles are national and universal, allowing CASRO and other national associations to ensure that research is (a) not confused with, (b) subsumed under, or (c) manipulated by other professions, industries, or activities.

  1. Research organizations shall ensure that participation in research is voluntary and based on informed consent.
  2. Research organizations shall respect the rights and well-being of individuals who participate in research, and shall make all reasonable efforts to ensure that individuals are not harmed or disadvantaged as a result of their participation in research.
  3. Research organizations shall make all reasonable efforts to protect the privacy of research participants and to keep personal information confidential and secure.
  4. Research organizations shall be honest, transparent, and straightforward in their professional and business relationships.
  5. Research organizations shall conduct research based on a consistent commitment to integrity, objectivity, and quality.
  6. Research organizations shall exercise independent and professional judgment in the design, conduct, documenting, and reporting of their research projects and activities.
  7. Research organizations shall ensure that research is conducted by persons with appropriate training, qualifications, and experience.
  8. Research organizations shall comply with all applicable national and international laws and regulations.

I. Responsibilities to Research Participants

Preamble

Research organizations have ethical and legal responsibilities to research participants. These ethical and legal responsibilities must be disclosed to research participants, thereby forming a "chain of trust” relationship between research organizations and research participants.
The research process is a systematic collection, aggregation, and/or analysis of opinions and behaviors for informational purposes.
The protections of personal information are governed by the principles of participant privacy and confidentiality, and the aggregation and reporting of research data.

The purpose of research is informational; there is no direct commercial intent or direct result in the activity of research. The research activity shall be the primary and prevailing purpose of the contact with the individual, and it is always separate and distinct from direct marketing, sales, and advertising activities. Research informs marketing; it does not achieve it.

Research participation may be active or passive:

a. Active Research Participation:

Research participation is considered active if an individual is asked to participate in research (e.g., a survey, a focus group, or other research project, either in-person or via some other means of communication, such as telephone, mail, or online). When research participation is active, the individual is most often referred to as the "respondent” as research surveys are typically used. In this situation, research participation is voluntary and is always based on informed consent. With active research participation, individuals must be: (a) willing participants in the research process; (b) appropriately informed (about the intentions of the research and how their personal information and responses will be used and protected); and (c) treated respectfully, in such a way as to maximize the likelihood that they will be satisfied with the experience and willing to participate in research in the future.

b. Passive Research Participation:

Research participation is considered passive if the individual does not personally engage in the research activity (examples include social media listening and mystery shopping). When research participation is passive, the individual is typically referred to as the "research participant” or "data subject.” In passive research participation, the individual’s behavior or actions typically are observed and recorded.
In passive research participation in public spaces, individuals may not be aware that their behavior is being observed and recorded and obtaining permission typically is not possible. In this situation, if the individual’s personal identity and/or personally-identifiable information are obtained in the process of observation or online data collection, the research organization shall protect the privacy and security of that information as required by law, this Code, and the standards of professional research practice. If personally-identifiable information cannot be de-identified, the research organization must delete the personal data or seek informed consent from the individual for any further research or data record use.

In passive data collection in non-public spaces, the research participant must be appropriately notified and permission obtained whenever possible. However, in cases where PII is collected in non-public spaces, the research participant must always be appropriately notified and his/her permission obtained.

In either circumstance of active or passive research participation, the research relationship between the research organization and the research participant is defined by, and limited to, the gathering of information. Research Organizations must take all reasonable efforts to ensure that there is no harm, harassment, or direct action taken against the individual based on his or her participation (active or passive) in research.

A. Privacy and Confidentiality

  1. Research organizations are responsible for protecting from disclosure to third parties--including research clients and the public--the identity of individual research participants as well as participant-identifiable information, unless the research participant expressly permits or requests such disclosure (or otherwise permitted in the exceptions in 3. below). In no circumstances, however, shall the permission to disclose participant-identifiable information be for the purpose of direct marketing, sales, or advertising.
  2. The principles of privacy and confidentiality include the following specific applications and safeguards:
    1. Research organizations' staff or personnel cannot use or discuss participant-identifiable data or information with any third party unless permission from the participant is obtained and the third party has executed a Non-Disclosure Agreement (NDA).
    2. The research organization has the responsibility for ensuring that subcontractors and consultants are aware of and agree to maintain and respect participant privacy and confidentiality whenever the identity of participants or participant-identifiable information is disclosed to such entities.
    3. Before permitting clients or others to have access to completed questionnaires or research data in circumstances other than those described in this Code, participant-identifiable data or information must be deleted.
    4. Invisible identifiers on mail questionnaires or other documents that connect participant data to particular participants must not be used. Visible identification numbers may be used but should be accompanied by an explanation that such identifiers are for control purposes only and that participant confidentiality will not be compromised.
    5. Any research organization that receives information from a client or other entity that it knows or reasonably believes to be participant-identifiable information must only use such information in accordance with the principles and procedures described in this Code.
    6. The use of survey or other research results in a legal proceeding does not relieve the research organization of its ethical obligation to maintain the privacy and confidentiality of participant-identifiable information or lessen the importance of participant privacy and confidentiality. Consequently, research organizations confronted with a subpoena or other legal process requesting the disclosure of participant-identifiable information must take all reasonable steps to oppose such requests, including informing the court or other decision-maker involved of the factors justifying participant confidentiality and interposing all appropriate defenses to the request for disclosure.
  3. The overarching principles of privacy and confidentiality are qualified by the following exceptions:
    1. The minimum necessary amount of participant-identifiable information may be disclosed to the client to permit the client:

    (1) to validate interviews and/or

    (2) to determine an additional fact of analytical importance to the study (including the practice of appending client-owned database information to the research organization's data file as an analytic aid). Where additional inquiry is indicated, research participants must be given a sound reason for the re-inquiry; a refusal by the participant to continue must be respected.

    Before disclosing participant-identifiable information to a client for purposes of interview validation or re-inquiry, the research organization must take whatever steps are needed to ensure that the client will conduct the validation or re-contact in a fully professional manner. This includes the avoidance of multiple validation contacts or other conduct that would harass or could embarrass research participants. It also includes avoidance of any use of the information (e.g., lead generation) for other than legitimate and ethical research purposes or to respond to participant complaints. Assurance that the client will respect such limitations and maintain participant confidentiality must be confirmed in writing before any confidential information is disclosed.

    Where participant-identifiable data are disclosed to clients so that the client’s internal research organization may analyze research data in combination with other participant-level data (such as internal customer data, participant-level data from another research project, etc.) it is understood that the information will be used for model building, internal (client’s internal research organization) analysis, research question targeting (for future research efforts), or the like rather than for individual marketing efforts, and that no action may be taken toward an individual participant simply because of his or her participation in the research project. To ensure client compliance, the research organization must obtain written confirmation from the client before releasing any data. (A suggested CASRO Client Agreement Clause is available.)

    Further, with respect to such research uses as database segmentation and/or modeling (see preceding paragraph), specific action(s) may not be taken toward an individual participant as a result of his/her research responses and participation beyond those actions taken toward the entire database population group of which the participant is a member. To initiate such specific action, the following two elements must be met:

(1) the participant has given permission to do so, having been informed as to what information is to be revealed, to whom, and the purpose and limitations of such use; and

(2) the research organization has obtained a written agreement from the client assuring that no other use will be made of participant-identifiable information.

Predictive equations or other techniques that integrate a segmentation scheme into a client database may be applied so long as no action is taken toward an individual participant simply because of his or her participation in the research project. Participants must be treated like all other individuals in the database according to the segment(s) to which they belong or have been assigned.

  1. The identity of individual participants and participant-identifiable information may be disclosed to other research organizations whenever such organizations are conducting different phases of a multi-stage study (e.g., a trend study). The initial research organization must confirm in writing that participant confidentiality will be maintained in accordance with the Code. In addition, the initial research organization’s privacy policy must clearly describe these practices.
  2. In the case of observation of in-person or online quantitative or qualitative research sessions or associated video or audio recordings, such observers must agree to keep confidential and not to disclose the identity of individual research participants or other participant-identifying information except as needed to respond, with the participant's prior specific approval, to any complaint that the research participant may have about a product or service supplied by the client.

B. Transparency and the Avoidance of Harassment

  1. Since research participants are the lifeblood of the research industry, it is essential that those approached to participate be treated with respect and sensitivity.
    1. The voluntary character of the interviewer-participant contact must be stated explicitly where the participant might have reason to believe that cooperation is not voluntary.
    2. Research organizations must respect the right of individuals to refuse to be interviewed or to terminate an interview in progress. Techniques that infringe on these rights must not be employed, but research organizations may make reasonable efforts to obtain an interview including:

    (1) explaining the purpose of the research project;
    (2) providing a gift or monetary incentive adequate to elicit cooperation;
    (3) re-contacting an individual at another time or providing a toll-free number for the individual to call back; or
    (4) providing an alternative method for the individual to participate (e.g., online).

  2. Research organizations shall be open, honest, and accountable in their relationship with research participants. This principle of transparency includes the following specific applications:
    1. The research organization, subcontractors, and interviewers shall make every reasonable effort to ensure that the participant understands the nature of the research project and the interviewer/participant contact.
      1. Deceptive practices and misrepresentation, such as using research as a guise for sales or solicitation purposes, are expressly prohibited.

    (1) The interviewer/research organization/sponsoring entity representative or the research invitation must provide prompt and honest identification of his/her research organization affiliation.

    (2) Participant questions must be answered in a forthright and non-deceptive manner, within limitations set by methodological considerations (e.g., research sponsor).

  3. Research participants will be protected from unnecessary and unwanted intrusions and/or any form of personal harassment:
    1. Research organizations shall exercise good and sensitive judgment in soliciting participation in research by contacting people at reasonable times and eschewing pressure to participate.
    2. Lengthy interviews can be a burden. Research organizations are responsible for weighing the research need against the length of the interview, and participants must be informed of the approximate duration of the interview.
    3. Research organizations are responsible for developing techniques to minimize the discomfort or apprehension of participants and interviewers when dealing with sensitive subject matter.
    4. Recording equipment, e.g., audio and video recording, photography, and one-way viewing rooms, may be used only with the knowledge of participants.
    5. Research organizations may utilize passive technologies, like identity validation, for the purpose of ensuring identities and fraud prevention. The informed consent or opt-in of the research participant is required for any other purpose.
  4. Informed Consent
    1. Additional assurances that informed consent has been obtained may be required in order to conduct research with certain segments of the population (e.g., children—see Section D).
    2. Additional assurances that informed consent has been obtained may be required in order to conduct research in certain countries.
  5. Disclosure of Client Identity
    1. Depending on requirements of (1) the law and regulation, (2) the CASRO Code, and (3) research best practices, research organizations may be required either to disclose client names to research participants or not to disclose client names to research participants. For example:

    (1) Law and regulation: In pharmaceutical research, some state laws require that client names cannot be disclosed to research participants.
    (2) CASRO Code requirements: Subject to the exceptions to in Section E. 1. e. below, if a research organization uses a client-supplied list of customers’ email addresses for research purposes, the research organization must identify the client, to whom the emailed individual has given permission to be contacted.
    (3) Research Best Practices: Client confidentiality may be required in order to avoid research bias.

C. Privacy Laws and Regulations

  1. Research organizations must comply with existing state, federal, and international statutes and regulations governing privacy, data security, and the disclosure, receipt and use of personally-identifiable information (collectively "Privacy Laws”). Some of the Privacy Laws affecting market, opinion, and social research are limited to specific industries (e.g., financial and health care industries), participant source (e.g., children), and/or international venues.
  2. In instances in which privacy laws apply to research operations for specific industries or participant source, research organizations will:
    1. Always enter into a confidentiality or "chain of trust” agreement when receiving and using legally-protected, personally-identifiable information from a source other than the research participant or data subject, ensuring that the research organization will protect the information and only use it for the purposes specified in the agreement;
    2. Always require subcontractors and other third parties to whom they disclose personally-identifiable information to enter into confidentiality or "chain of trust” agreements that require such party(ies) to provide the same level of security and limitations of use and disclosure as the research organization;
    3. Always store or maintain personally-identifiable information in a secure manner;
    4. Always control and limit accessibility to personally-identifiable information;
    5. Always use reasonable efforts to destroy or effectively secure personally-identifiable information once the research project is complete and validation has been conducted, unless the personally-identifiable information relates to participants in panels, to ongoing studies, or for some other critical research reason; or the research client is legally or contractually obligated to require its research providers to maintain such information for a certain period of time and contractually imposes this requirement on the research organization;
    6. Never knowingly receive, use or disclose personally-identifiable information in a way that will cause the research organization or another party to violate any privacy law or agreement.
  3. In order to conduct international research that requires either transmitting or receiving personally-identifiable information of research participants, research organizations must comply in all material respects with international privacy laws and regulations. In the case of data transfers with a person or entity in the European Union, either by certifying their compliance with the privacy provisions described in the US-EU Safe Harbor Framework or by satisfying an alternative method of complying in all material respects with the European Union Data Protection Directive. The US-EU Safe Harbor privacy principles are contained in the CASRO Model Privacy Policy and are as follows:
    1. Notice: A description of what information is collected, how it is collected, its purpose, and its disclosure to third parties.
    2. Choice: A statement of and procedures for allowing individuals to choose not to participate in the research and/or to have their personal information used or disclosed to a third party.
    3. Onward Transfer: A statement that personal information will be transferred only to third parties who also are in compliance with the Safe Harbor Principles.
    4. Access: Procedures to provide individuals with access to their personal information in order to correct, amend, or delete that information where it is inaccurate.
    5. Security: A description of the reasonable precautions taken to protect personal information from loss, misuse and unauthorized access, disclosure, alteration, and destruction.
    6. Data Integrity: A statement that information will be used consistent with the purpose for which it was collected.
    7. Enforcement: A description of internal and external mechanisms for assuring compliance, and addressing and resolving disputes and complaints.
  4. Research organizations will, to the extent required by law or as necessary to fully and completely comply with the principles set forth in the section of this Code entitled Responsibilities to Research Participants, adopt effective and comprehensive legal and operational policies, such as those set forth in CASRO's Privacy Protection Program, which will be updated as necessary to conform with additions to and changes in privacy laws.
  5. Research organizations shall provide or have readily accessible a privacy policy that details their corporate, professional policies and compliance to relevant privacy laws.

D. Children, Young People, and Vulnerable Populations

Conducting research with children and young people includes the requirement for research organizations to protect their privacy and interests, as well as to respect and adhere to the wishes of their parents or guardians. This requirement becomes increasingly critical the younger the child and the more sensitive the subject matter. In addition, the laws governing interviewing children and the age at which children become young people and then adults varies from country to country and, sometimes within countries, from state to state. In the U.S., the Children’s Online Privacy Protection Act (COPPA) requires verifiable parental or the legal guardian’s consent for interviewing children below the age of 13 years. Consequently, prior to conducting a research project with children or young people, research organizations should (i) identify and comply with any applicable laws and (ii) consult with their legal counsel.

E. Special Considerations for Online and Mobile Research

The unique characteristics of online and mobile research require specific notice that the principle of participant privacy applies to these research methodologies. The general principle guiding this section of the Code is that research organizations will not use unsolicited emails or text messages to recruit research participants or engage in surreptitious data collection methods.

  1. Email and Text Message Solicitation.
    1. Research organizations are required to verify that individuals contacted for research by email or text message have a reasonable expectation that they will receive email or text message contact for research. Such agreement can be assumed when ALL of the following conditions exist:

    (1) A substantive pre-existing relationship exists between the individuals contacted and the research organization, the client supplying email addresses or mobile phone numbers, or the sample providers supplying the email addresses or mobile phone numbers (the latter being so identified or linked to by the email invitation or text message);

    (2) Potential research participants who are sent email invitations or text message invitations have a reasonable expectation, based on a pre-existing relationship where email or text message invitees have specifically opted-in for online or mobile research with the research organization or sample provider, or in the case of client-supplied lists that they may be contacted for research and they have not opted-out of email or text message communications;

    (3) Email invitations on text message invitations to potential research participants clearly communicate or link to the name of the sample provider, the relationship of the individual to that provider, and clearly offer the choice to be removed from future email or text message contact;

    (4) The email sample or mobile phone number list excludes all individuals who have previously requested removal from future email or text message contact in an appropriate and timely manner; and

    (5) Participants in the email mobile phone sample were not recruited via unsolicited email or text message invitations.

    1. Research organizations are prohibited from using any subterfuge in obtaining email addresses or mobile phone numbers of potential participants, such as collecting email addresses or mobile phone numbers from public domains, using technologies or techniques to collect email addresses or mobile phone numbers without individuals' awareness, and collecting email addresses or mobile phone numbers under the guise of some other activity.
    2. Research organizations are prohibited from using false or misleading return email addresses or any other false and misleading information when recruiting participants. As stated previously in this Code, research organizations must comply with all federal regulations that govern market, opinion, and social research activities. In addition, research organizations should use their best efforts to comply with other federal regulations that govern unsolicited email and text message contacts, even though they do not apply to research.
    3. When receiving email lists or mobile telephone lists from clients or sample providers, research organizations are required to have the client or sample provider verify that individuals listed have a reasonable expectation that they will receive email contact or text message, as defined, in (1) above.
    4. The practice of "blind studies” (for sample sources where the sponsor of the study is not cited or linked to in the email solicitation or text message) is permitted if disclosure is offered to the participant during or after the interview. The participant must also be offered the opportunity to "opt-out” of this research project and also, if so requested, from the sample source list.
    5. Other messaging technologies such as mobile application (mobile app) notifications can have characteristics and capabilities that are similar to text messages. Accordingly, when using messaging technologies such as mobile app notifications for research, research organizations must comply with any applicable requirements of this section.
    6. Information about the CASRO Code of Standards and Ethics should be made available to participants.

II. Responsibilities to Clients

  1. Relationships between a research organization and clients for whom the research project is conducted should be of such a nature that they foster confidence and mutual respect. They must be characterized by honesty and confidentiality.
  2. The following specific approaches describe in more detail the responsibilities of research organizations in this relationship:
    1. A research organization must assist its clients in the design of effective and efficient studies that are to be carried out by the research organization. If the research organization has misgivings about whether a study design will provide the information necessary to serve the client's purposes, it must make its reservations known.
    2. A research organization must conduct the study in the manner agreed upon. However, if it becomes apparent in the course of the study that changes in the plans should be made, the research organization must make its views known to the client promptly in writing.
    3. A research organization has an obligation to allow its clients to verify that work performed meets all contracted specifications and to examine all operations of the research organization that are relevant to the proper execution of the project in the manner set forth. While clients are encouraged to examine questionnaires or other records to maintain open access to the research process, the research organization must continue to protect the confidentiality and privacy of research participants.
    4. When more than one client contributes to the cost of a project specially commissioned with the research organization, each client concerned shall be informed that there are other clients (but not necessarily their identity).
    5. Research organizations will hold confidential all information that they obtain about a client's general business operations, and about matters connected with research projects that they conduct for a client.
    6. For research findings obtained by the research organization that are the property of the client, the research organization may make no public release or revelation of findings without expressed, prior approval from the client.
  3. Bribery in any form and in any amount is unacceptable and is a violation of a research organization's fundamental, ethical obligations. A research organization and/or its principals, officers and employees should never give gifts to clients in the form of cash. To the extent permitted by applicable laws and regulations, a research organization may provide nominal gifts to clients and may entertain clients, as long as the cost of such entertainment is modest in amount and incidental in nature.

III. Responsibilities in Reporting to Clients and the Public

  1. When reports are being prepared whether for client confidential use or public release purposes, it is the obligation of the research organization to ensure that the findings they release are an accurate portrayal of the research data, and careful checks on the accuracy of all figures are mandatory.
  2. A research organization should supply in its reports or be ready to supply on short notice to a client or to the public as applicable, the following information about the research:
    1. The name of the organization for which the study was conducted and the name of the organization conducting it.
    2. The purpose of the study, including the specific objectives.
    3. The dates on or between which the data collection was done.
    4. A definition of the universe that the research is intended to represent and a description of the population frame(s) that was actually sampled.
    5. A description of the sample design, including the sample source, the method of selecting sample elements, method of interview, cluster size, number of callbacks, participant (respondent) eligibility or screening criteria, and other pertinent information.
    6. A description of results of sample implementation including (a) a total number of sample elements contacted; (b) the number not reached; (c) the number of refusals; (d) the number of terminations; (e) the number of non-eligible; and (f) the number of completed interviews.
    7. The basis for any specific "completion rate" percentages must be fully documented and described.
    8. The questionnaire or exact wording of the questions used, including interviewer directions and visual exhibits.
    9. A description of any weighting or estimating procedures used.
    10. A description of any special scoring, data adjustment or indexing procedures used. (Where the research organization uses proprietary techniques, these must be described in general and the research organization must be prepared to provide technical information on demand from qualified and technically competent persons who have agreed to honor the confidentiality of such information).
    11. Estimates of the sampling error and of data should be shown when appropriate, but when shown they should include reference to other possible sources of error so that a misleading impression of accuracy or precision is not conveyed.
    12. Statistical tables clearly labeled and identified as to questionnaire source, including the number of raw cases forming the base for each cross-tabulation.
    13. Copies of interviewer instructions, validation results, code books, and other important working papers.
    14. In some cases the source of the data used to prepare a report may permit the research organization access to an entire population of interest (a census rather than a sample). Examples can include customer transaction data and billing data. In such cases, the requirements for reporting information about a sample do not apply. However, when reporting to clients or the public, the research organization must comply with any applicable requirements of this section when using such data sources.
  3. At a minimum, any general public release of research findings should include the following information:
    1. The sponsorship of the study.
    2. A description of the purposes.
    3. The sample description and size.
    4. The dates of data collection.
    5. The name of the research organization conducting the study.
    6. The exact wording of the questions.
    7. Any other information that a layperson would need to make a reasonable assessment of the reported findings.
    8. Information required for the computation of any reported sample error.
    9. In some cases the source of the data used to prepare a report may permit the research organization access to an entire population of interest (a census rather than a sample). Examples can include customer transaction data and billing data. In such cases, the requirements for reporting information about a sample do not apply. However, when reporting to clients or the public, the research organization must comply with any applicable requirements of this section when using such data sources.
  4. A research organization will seek agreements from clients so that citations from research project reports will be presented to the research organization for review and clearance as to accuracy and proper interpretation prior to public release. A research organization will advise clients that if the publicly-disclosed research data are incorrect, distorted, or incomplete in the research organization's opinion, the research organization reserves the right to make its own release of any or all research data necessary to make clarification.

IV. Responsibility to Subcontractors and Interviewers

  1. Research organizations will not ask any subcontractor or interviewer to engage in any activity that is not acceptable as defined in other sections of the Code of Standards and Ethics or related CASRO publications.

Introduction

This document describes the coding standard used by the Workspace developers. It reflects the desired style and conventions to be used throughout the Workspace code base. Older code may not yet adhere to the advice given here, so such cases should be brought into compliance as developers encounter them where practical. For the most part, this standard addresses C and C++ code, but some items are applicable more broadly to other languages, tools or formats used or supported by the build system.

We welcome other groups adopting these coding standards for their own work. In particular, we encourage Workspace plugin developers to consider following these conventions so that others using their work will have a certain level of familiarity with the overall style.


General

Spelling conventions

  • Use US English for all source code, documentation, file and directory names.
  • If you want to support Australian English in a user interface, use a Qt translation file.

Names

  • In general, avoid using abbreviations except for very well-known cases (eg , , etc.).
  • Try to avoid carrying across poor names from other code bases (especially variables). Instead, include a comment where the entity is defined to indicate the old name.
  • A few special abbreviations are used by the Workspace code base because they occur very frequently and they prevent overly verbose code:
    • loop counters are frequently named , or
    • Loop iterators are often abbreviated to (this differentiates them from ordinary integer counters such as ).
    • File and class names use instead of .

Namespaces and classes

  • Names must contain only letters and numbers (note: no underscores).
  • Each word within the name should start with an uppercase letter, including the start of the name.
  • All other characters should be lowercase, even for acronyms.
  • As a special exception, namespace names which are a single acronym may have all characters in uppercase (eg CSIRO).
Correct Incorrect
SomeProgClass Some_Prog_Class
someProgClass
Someprogclass
VtkWriter VTKWriter
Application APPLICATION

Functions and macros

  • The rules for function names are the same as for class names, except that function names must begin with a lowercase letter.
  • Function parameter names should follow the rules for variables.
  • Names of function-like macros should follow the same rules as functions.
  • Do not use prototypes where the parameters are specified with a type only, include meaningful names.
  • If a parameter type is a reference or pointer, the trailing & or * should be placed with the type, not the variable name.
  • If a parameter is being passed by value, do not include a specifier
Note
It is meaningless as far as the function signature is concerned to have a specifier on a function parameter passed by value. The compiler silently ignores it when matching calls to the function.
Correct Incorrect
getBigThings() GetBigThings()
get_big_things()
getbigthings()
GETBIGTHINGS()
getBigThings(int key, QString value) getBigThings(int, QString)
getBigThings(int numItems) getBigThings(int n)
getBigThings(double* ptr) getBigThings(double *ptr)
getBigThings(int numItems) getBigThings(const int numItems)

Variables

  • Non-member variables (local, global, file-scope statics and function parameters) have the same name rules as function names.
  • Member variables (static or non-static) have the same name rules as function names with the following variations/restrictions:
    • The variable name must end with a trailing underscore.
    • If the class has only public variables and no member or static functions, the trailing underscores can be omitted.
    • Do not use a prefix such as on the name.
    • Avoid using or similar in the name for member variables that hold pointers.
  • For const references, the keyword should be placed before the type, as in .
  • For pointers to const objects, the placement of const is similar to that of references, ie .
  • For a const pointer to something (which is much less common), the keyword has to be placed between the and the variable name, as in .
Note
For an explanation of the differences between the various const pointer types, see the C++ FAQ at http://www.parashift.com/c++-faq-lite/const-correctness.html#faq-18.5

Enums

The rules for enums are the same as for class names. This applies to both the enum name (ie its type identifier) and to the names of its values (ie its enumerators).

Typedefs and other types

The rules for typedefs are the same as those of the entity they are typedef'ing. For example, a typdef for a class should conform to class name rules.

XML tags

The rules for XML tags are the same as for class names, except that all characters should be in lowercase.

File system

This section covers naming items in the file system within the source tree. It is not necessarily meant to be applied to files created or used by the software at run-time, although the rules specified here would often be a useful guideline.

Directories

  • Prefer to name your directories in the same form as you would class names (ie begin with a capital letter and use camel-case thereafter).
  • For certain specific cases where there is already a long-established convention (eg bin, lib, doc and so on), the long-accepted name can be used, but this should be rare and is not preferred.

Files

  • Names of files used as part of the build should consist of only lowercase letters and numbers.
  • File names should always start with a letter.
  • Underscores should not be used in source file names except for the following special cases:
    • Test source files should follow the naming convention of the form (see Tests).
    • Source files may append an underscore followed by a platform-specific suffix on the base name of the file.
    • Images, XML files and other non-source files may use underscores if necessary, but prefer to avoid underscores for consistency with source files where possible.
Correct Incorrect
somesourcefile.cpp some_source_file.cpp
someSourceFile.cpp
file1.cpp 1file.cpp
file_1.cpp
test_foobar.cpp testfoobar.cpp
foobar_test.cpp
foobartest.cpp
foobar_win32.cpp
foobar_mac.cpp
foobar_linux.cpp
foobarwin32.cpp
mac_foobar.cpp
foobar-linux.cpp
  • File name extensions should not be more than three characters long and should be lowercase.
  • Exceptions can be made for long-established conventions such as
  • Use familiar file name extensions and adhere to the following conventions:
File Type Extension
C source .c
C++ source .cpp
C/C++ header .h
C/C++ source with doxygen comments only .dox
Qt Designer UI file .ui
Qt resource file .qrc
HTML source .html
JPEG image .jpg

Tests

  • Most C++ tests will be defined in a file named where is the name of the test and would follow the same rules as an ordinary C++ source file name.
  • For C++ tests spanning multiple source files, the test file that contains should be named as above. Other source files follow the usual rules for source files.
  • Tests written in other languages are encouraged to follow a similar naming structure as for C++.
Correct Incorrect
test_foobar.cpp testfoobar.cpp
foobar_test.cpp
foobartest.cpp

Pre-processor defines

  • Where possible, pre-processor defines should be avoided in favour of variables or enums, since those offer much better type safety than a .
  • Inlined functions should also be preferred over function macros for similar reasons.
  • Where a is used to define a value, the name of the symbol being defined should consist only of uppercase letters, numbers and underscores.
  • Where the name of a contains more than one word, underscores can be used to separate the words for readability.
  • Where a is used to define a function macro, the name of the function macro and the names of the function macro's parameters should follow the same rules as for an ordinary function.

Headers

Header guards

  • All header files must have a header guard defined, whether it is expected that the header will be included by multiple files or not. This also applies to headers.
  • The name used for a header guard should be to take the fully scoped name of the class defined in that header, convert all names to uppercase and scoping operators to an underscore, then append .
  • For the cases where a header defines more than one class (which is strongly discouraged), use the main class defined by the header to form the header guard name.
  • Where a header provides no classes, some other substitute should be used for the class name, such as a function or type that the header provides (including the namespaces, if present).

The standard form of a header guard is as follows:

// Copyright header would be included first.... #ifndef CSIRO_GUMBY_FOOBAR_H #define CSIRO_GUMBY_FOOBAR_H namespace CSIRO { namespace Gumby { class FooBar { // ... }; }} #endif

Forward declarations

In header files, use forward declarations rather than a full if:

  • Nothing in the header requires more than a forward declaration.
  • A developer would not intuitively expect the full header to have been included.

Header ordering and placement

  • Use the following header inclusion order:
    • Standard C/C++ headers
    • Qt headers
    • Your own headers
  • Place headers before all code.
  • Do not place a before headers, other than to work around a compiler limitation or bug.

Using directives

Do not put a using directive in a header file other than for one of the following cases:

  • Inside a class for a base class function for which an override is being defined in the subclass
  • To support backwards compatibility when a symbol is moved from one namespace to another. In this situation, only apply the directive to the renamed symbol. The effect of the directive should be kept to the minimum required in order to achieve backwards compatibility for the renamed symbol.

Self-sufficiency

  • It should be possible to any header on its own (whether internal or public) and not generate a compiler error due to missing symbols, etc.
  • No header should depend on another header having been included before it.
  • Headers should also not generally depend on a particular symbol being defined before the header is included (it should its own set of headers as necessary to provide that symbol).

Comments

Copyright notices

  • Every source file should have a copyright notice at the very top. This includes:
    • Headers (),
    • Implementation files (, )
    • CMake project files ()
  • Other text-based, source-like files that have support for comments should also generally contain a copyright notice.

The standard notice used for all Workspace code is the following:

============================================================================ Revision: $Revision: $ Last changed: $Date: $ Copyright 2018 by: Commonwealth Scientific and Industrial Research Organisation (CSIRO) This file is licensed by CSIRO under the copy of the CSIRO Binary License Agreement included with the file when downloaded or obtained from CSIRO (including any Supplementary License). If no copy was included, you must obtain a new copy of the Software from CSIRO before any use is permitted. For further information, contact: workspace@csiro.au This copyright notice must be included with all copies of the source code. ============================================================================
  • Plugin developers should come up with their own appropriate copyright notice rather than use the one above.
  • Plugin code should generally use a consistent copyright notice across all its source files.

Doxygen comments

  • Doxygen is the documentation system used throughout the Workspace project. Do not use MS Word, OpenOffice, LaTeX or other forms for documents.
  • As far as is reasonable, all documentation sources should be in doxygen-compatible form.
  • The Workspace code uses the backslash form for doxygen commands rather than the @ form to avoid potential issues with CMake misinterpreting the @ symbol.
  • Multi-line comments generally have each line starting with an asterisk (see examples further below).
  • Documentation blocks should be adjacent to the entity they are documenting, usually being placed immediately before the entity (variables and enums may have short trailing comment blocks).
  • The documentation block for a particular entity should generally be placed where that entity is defined, not declared.
  • When referring to a function by name, include brackets but not parameters (unless you need to distinguish a specific overload).

Classes

  • Classes have their comment block before the class definition, not where the class might be forward declared.
  • All class definitions should have a doxygen comment block and that documentation block should not be empty.
  • If the class is part of the public interface, it must have a one-line statement at the top, followed by a blank line.
  • The brief description should not be excessively long. Save longer descriptions for the class details.
  • If the class is an internal implementation detail, the comment block should contain an command on the first line, on its own.
  • Any additional documentation after an directive is optional.
  • If the class is a template class, the template parameters should be defined with and appear after the section, but before the main description of the class.
  • Following the class description, any or (ie "see also") blocks should be included. These should be the last sections in the documentation block.
/** * \brief Implements a specific magic trick * * This class does all sorts of interesting things. * Most of it is magic, some is just pure genius. * * \relates PerformMagic */ class MagicTrick { // Contents of the public class }; /** * \brief Example of a template class * * \tparam TrickT Specifies the type of trick the class defines */ template<typename TrickT> class PerformTrick { // Contents of the public class }; /** * \internal */ class HiddenSecret { // Move along, nothing to see here... };

Functions

  • Functions are generally documented where the function body is defined, not in the header file where it will usually have been declared.
  • If a function has no implementation (eg a pure virtual function), it should be documented where it is declared, which is usually in a header.
  • All function implementations should have a doxygen comment block, even if it is left empty. Note that this also applies to member functions of internal implementation classes.
  • There should be two blank lines above a function documentation block to separate it from the preceding block (this makes it much easier to find functions in text editors that support syntax highlighting).
  • All functions that are part of the public interface should have non-empty comment blocks unless:
    • The function name already makes clear what the function does and
    • No further information needs to be provided to the developer
  • All function parameters should be documented with their own entry at the start of the comment block.
  • If the function is a templated function, the template parameters should be defined with and appear before the regular function parameters.
  • If you need to refer to a parameter by name somewhere in the documentation block, use the doxygen command with it to ensure it is formatted correctly.
  • Return values should be documented with the command, usually at the end of the comment block.
  • The detailed description of what the function does, etc. usually sits between the parameters and the return value details.
  • Any pre-conditions for the function can be explicitly stated with the command, usually placed before or after the description (whichever is more readable)
  • The same applies to post-conditions explicitly stated with the command.
  • If the function is a setter or getter, its companion function should be referenced with a (ie "see also") command.
  • Any other functions that have a close relationship to the one being documented should also be listed in the command.
  • If present, the block should always be the last section in the documentation block.
// ... end of previous function } /** * \param xFactor Some value that does extra special things. * \param required Switch specifying whether we want to use the \a xFactor. * * This function does some magical computation. It uses \a xFactor * only when \a required is \c true. Otherwise, it uses some other value. * * \return The magic factor, or pi if you are hungry. * * \sa foolGeneralPublic() */ double computeMagic(double xFactor, bool required) { // .... }

Enums

  • Any that is part of the public interface must be documented. A description of the (without using the command) is sufficient.
  • Each item in an should also be documented.
  • Unlike other documentation blocks, the blocks for items in an are usually placed after the item, as per the following example:
/** * Specifies what sort of magic tricks can be requested. */ enum SupportedMagicTricks { SleightOfHand, //!< Standard magician's trick Misdirection, /*!< This can be a bit more involved which is why its description is longer */ GrandIllusion //!< Not going to spoil the surprise! };

Variables

Note
Variables are not normally made accessible directly in public classes and global variables are to be avoided, so most variables will be private implementation details. As such, variables do not generally need to be documented unless the developer wants to make some non-obvious detail clear. A common example would be to document some assumption about how the variable is used.
  • Local variables within functions, etc. can be documented however the developer sees fit, as long as readability is maintained and it is clear to others what the variables mean and how they are used.
  • Ordinary C/C++ comments are appropriate for variables rather than the special form used by doxygen.

Formatting

Defining variables

  • Variables should be declared one per line.
  • Any asterisk’s (*) or ampersands (&) that are used to specify that a variable is a pointer or reference respectively should be associated with the variable’s type, not with its name.
Correct Incorrect
int varOne;
int varTwo;
int varOne, varTwo;
int* varOne;
int& varTwo = ...;
int *varOne;
int &varTwo = ...;

Placement of curly braces

  • All scope blocks for classes, namespaces, enums, if, for, while, functions, etc. should uses the same formatting for curly braces.
  • The opening brace and closing brace should both be on their own separate line.
  • Inside class definitions, trivial function implementations may be included on the same line as the function name as long as the resultant line is not overly long.
  • Always use braces in flow control statements. Omitting braces can have unexpected consequences. For example:
    /** * Some bad code */ #define PRINT_VALUES(value1, value2) \ cout << value1; \ cout << ", "; \ cout << value2; void someFunction(bool choice) { if(choice) PRINT_VALUES(1, 2); } expands to:
    void someFunction(bool choice) { if(choice) cout << 1; cout << ", "; cout << 2; } which is not what the writer would have intended. Always using braces avoids this pitfall.
Correct Incorrect
if (someExpression == true)
{
    // Do something
}
if (someExpression == true) {
    // Do something
}
Within a class definition only...
int getFoobar() const { return foobar_; }

if (someExpression == true) { doSomething(); }

Constructors

  • The initialisation lists for a constructor should generally place each item on its own line unless the number of items is small and they all fit comfortably on one line.
  • For multi-line initialisation lists, place commas at the end of a line (ie after a variable), not at the start (ie not before a variable).
  • Place the colon on the same line as the function name, with a space between the closing parenthesis and the colon for readability.
  • In normal circumstances, do not list variables or base classes if they are simply invoking the default constructor.
Correct Incorrect
Foo::Foo(int a, int b) : a_(a), b_(b) {} Foo::Foo(int a, int b) : // Something really long... ;)
Foo::Foo(int a, int b) :
    a_(a),
    b_(b)
{
}
Foo::Foo(int a, int b)
    :
    a_(a),
    b_(b)
{
}

Foo::Foo(int a, int b) :
      a_(a)
    , b_(b)
{
}

Indentation

  • Tab characters should not be inserted into source files, insert spaces instead.
  • The standard indentation size is four spaces.

The indentation guidelines are best shown by example:

/** * \brief Main outer namespace */ namespace A { /** * \brief Inner namespace for fun toys * * To avoid excessive indenting, don't indent inner namespaces .... */ namespace B { // .... unless it is an anonymous or private namespace, in which // case you can indent it or not depending on your own preference namespace { // ... } /** * \brief Does nothing interesting */ class Foo : public JustOneBase { // ... }; /** * \brief Does some more interesting things */ class Bar : public BaseOne, // Indent multi-line base classes public BaseTwo { double var1_; // Access specifiers have same indentation as the class keyword public: Bar(); int getCrazyValue(int b); /** * \brief Inner class for interesting stuff */ class Nested { // ... Same rules as for regular non-nested classes } /** * Toys for the adrenalin junky */ enum CoolThings { Snowboards, //!< For cold weather only DrumKits //!< Use when neighbours are away }; }; /** * \param b Mystery switch * * \return A crazy value of little use. */ int Bar::getCrazyValue(int b) { int a = 1; for (int i = 0; i != 20; ++i) { // Don't indent curly braces.... a += i; // ... only indent the stuff within the braces } switch (b) { case 7: // Don't indent the case keywords ... a += 42; // ... but do indent the case body break; case 2: a -= 27; break; default: a += b; } return a; } }}

Implementation

The following are a set of implementation guidelines not already covered by preceding sections. They are designed to provide some consistency in coding style and to avoid common programming pitfalls or suboptimal code. Many of these are discussed in more detail in the excellent book "C++ Coding Standards", by Herb Sutter.

Interfaces

  • Aim for "one entity, one responsibility". Eg, don't write classes that have multiple responsibilities.
  • Classes in the public API should hide their implementation using the pointer to implementation idiom. The name of the pointer is always in all Workspace code.
  • Exceptions to the pointer-to-implementation rule can be made for the following cases:
    • Performance-critical classes
    • Fully inlined or template classes
    • Classes that will only ever be used by one thing, such as a main application class with no prospect for re-use
    • Tutorial or example code where simplicity is of greater importance
  • Where public classes do have variables, make them private. Subclasses and external code should only access these variables via member functions.
  • Use proactively. If a member function does not modify an object's data, make it .
  • Do not return non- references from a function.
  • Avoid providing type conversion operators for a class unless it is genuinely intuitive for the developer to expect them (eg math-related classes).
  • Do not use anything from the STL in a public interface.
  • Do not include any STL header in one of your own public headers.
Note
The reason for excluding STL in the public API or headers is to allow clients to switch to a different STL implementation (eg STLPort). It may also be necessary on some platforms to ensure binary compatibility.

Signals and slots

The following are in addition to the rules for ordinary member functions:

  • Any types used as parameters must be fully scoped in the class definition, otherwise code in other namespaces cannot reliably create signal-slot connections.
  • Signals must always have return type .
  • Slots should also generally return since they should be designed primarily for code that will ignore any return value.

Exceptions

  • Use of exceptions is permitted, but prefer other mechanisms.
  • Do not use exception specifications on functions.
  • All exceptions must be caught within the shared library that generates them. Exceptions cannot be reliably caught by type across shared library boundaries.

See Scott Meyers' book "More Effective C++" for further good advice on exceptions.

C++ language

  • Do not use .
  • Avoid initialisation dependencies across compilation units. Initialisation of an object in one file must not depend on an object from a different file being initialised, since the order of initialisation is not defined by the C++ standard.
  • Do not call virtual functions in constructors or destructors (they act as non-virtual in these contexts).
  • Avoid using except to work around const-correctness bugs in third party code.
  • Avoid using except where required to be compatible with low level Qt code (very rare).
  • Do not use C-style casts, use the C++ style or as appropriate instead.
  • Avoid type switching with or statements. Prefer proper class design with virtual functions or templated solutions.
  • Prefer to use iterators ahead of raw integer indexes into containers.
  • Declare variables as locally as possible (ie declare them at the point where you need them).
  • Avoid long function bodies. Break them up into smaller chunks to improve readability.
  • Prefer prefix and operators over postfix. Eg, is preferred over where either could be used.
  • Use liberally to verify any assumptions or as a defensive measure to catch problems early.
  • Compile cleanly at high warning levels and don't ignore compiler warnings.

References

The following are some references that have had a strong influence on the Workspace source code, both in terms of style and implementation. They are highly recommended for anyone interested in C++ development in general.

  • "C++ Coding Standards: 101 Rules, Guidelines, and Best Practices", Herb Sutter
  • "Effective C++", Scott Meyers
  • "More Effective C++", Scott Meyers
  • "Effective STL", Scott Meyers
  • "C++ Templates - The Complete Guide", David Vandevoorde and Nicolai M. Josuttis
  • "Design Patterns: Elements of Reusable Object-Oriented Software", Gamma, et. al.
  • http://www.sgi.com/tech/stl/table_of_contents.html
  • http://www.parashift.com/c++-faq-lite/

0 comments

Leave a Reply

Your email address will not be published. Required fields are marked *