EPICS SOFTwARE CODE RUBRIC
Outcome Expected Acceptable Unacceptable
The code performs as intended
The code produces the desired performance in a timely, straightforward, consistent, concise, simple, and logical manner without extraneous elements
The code produces the desired performance, but includes elements that add to processing time, adds unnecessary complexity, unnecessarily lengthens the code, contains inconsistencies, or obscures logic
Code fails to perform
The code is human readable
The code itself and corresponding documentation are easily understood by a person with a basic understanding of the coding language used. The code is straightforward and intuitive
The code and
documentation are easily understood in most places. In some places coding is convoluted or wordier than is necessary.
The code and documentation are generally not easily understandable. The code includes esoteric coding strategies
The code contains meaningful names
Meaningful names—names that clearly convey the distinct purpose, behavior, or intent of a particular element of the code—are used in all facets of the code, including variables, procedures, functions, classes, and objects.
Names should be distinct, descriptive, non-redundant, and technically correct.
Meaningful names are used in most of the facets of the code, including variables, procedures, functions, classes, and objects
Meaningful names are used only occasionally in the facets of the code, including variables, procedures, functions, classes, and objects
The code is
consistent The code follows standardized rules, conventions, or a consistent logical pattern in its structure, format, and use of names
The code generally follows standardized rules, conventions, or consistent logical patterns in its structure, format, and use of names
The code occasionally or rarely follows standardized rules, conventions, or consistent logical patterns in its structure, format, and use of names
Continued
The structure and layout of the code is appropriate and logical
The structure and layout of the code consistently follows a logical order that conveys meaning to the reader. Variables are always placed in close proximity to their use
The structure and layout of the code generally follows a logical order that conveys meaning to the reader. Variables are often placed in close proximity to their use.
The structure and layout of the code does not follow a logical order that conveys meaning to the reader. Variables are not placed in close proximity to their use
The code makes appropriate use of comments
Comments in the code are consistently clear, concise, and informative and consistently explain intent or assumptions made by the author as needed. Comments in the code always contain appropriate information about the code and do not duplicate other sources of documentation.
Comments appear as close to the part of the code they refer to as possible. Comments reflect the current state of the code and have been updated when the code was updated
Comments in the code are usually clear, concise, informative, and sufficient in explaining intent or assumptions made by the author. Comments in the code generally contain appropriate information about the code, but may duplicate other sources of documentation.
Comments often appear close to the part of the code they refer to.
Comments generally reflect the current state of the code
Comments in the code are occasionally clear, concise, and informative and do not really explain intent or assumptions made by the author.
Comments in the code do not generally contain appropriate information about the code, or often duplicate other sources of documentation.
Comments do not appear close to the part of the code they refer to.
Comments are outdated and do not reflect the current state of the code
EPICS SoftwarE doCuMENtatIoN rubrIC
Outcome Expected Acceptable Unacceptable
Documentation describes functionality of code
The documentation includes clear information on the purpose of the code and what the code does
The documentation only partially describes the purpose and functionality of the code, and is at times unclear to non–team members.
Documentation omits minor details
The documentation fails to describe the purpose and functionality of the code in a way that is understandable to non–team members.
All constituent parts of the software code and accompanying hardware/documentation are identified, and interrelationships between the parts are clearly identified
Most constituent parts of the software code and accompanying hardware/documentation are identified, and most interrelationships between the parts are clearly identified. Documentation omits minor details
Significant numbers of constituent parts are not identified and/or the interrelationships are not adequately identified to enable non–team members to orient themselves to the software package. Documentation omits multiple and/or important details
Continued
Documentation
Changes are tracked via a versioning system;
ownership of changes is clearly noted in the documentation so that future team members can retrieve background information from blogs/
notebooks
The majority of changes are tracked; ownership of changes is not always identified
Changes aren’t recorded and responsibility for those changes is not recorded consistently.
All interfaces and human interaction points with the software are documented, along with the software designer’s decision-making process for those interactions
Interfaces are identified, but it is not clear to future team members why or how those decisions were made. Documentation omits minor details
Interfaces are not identified. Neither are decisions identified.
Documentation omits multiple and/or important details. The future team member must make assumptions or create a backstory for code decisions made Documentation
describes the software environment
All hardware, operating systems, programming languages, compilers, software libraries, other software packages, and peripherals necessary for using/understanding the code have been identified
There have been oversights in listing component systems and languages.
Documentation omits minor details
Little or no attempt has been made to collocate the components the software design and programming relies upon. Documentation omits multiple and/or important details
In the case of databases and apps, decisions on the architecture (backups, client/server operations, or peer-to-peer interactions) have been fully explained in the documentation
The system architecture is understood, but requires research in the code in order to identify the underlying architecture fully. Documentation omits minor details
The documentation does not have enough information for the underlying architecture of the system to be easily understood and the code does not make it clear. Documentation omits multiple and/or important details
Documentation is up to date for all changes to that point in the semester.
Documentation is digitally signed by the code author and dated
Documentation is somewhat behind the current state of the code.
Documentation is digitally signed by the code author and dated
Documentation is completely out of date and/or has not been signed and dated by the code author