5. Glossary
- astutely
done in a way as to be clever and quick at seeing what to do in a particular situation, especially how to get an advantage
- compatibility
As a quality factor of source code, compatibility is the ease of combining source-code modules elements with others.
- context
noun, the situation in which something happens and that helps you to understand it. This one-page article about context is probably the best extended definition I could refer you to.
- correctness
As a quality factor of source code, correctness is the ability of the generated software system to perform its exact tasks, as defined by its specification.
- documentation
Documentation itself is not a separate quality factor, but appears as a consequence of the other quality factors. Let us distinguish between three kinds of documentation:
External documentation, which enables users to understand the power of a system and use it conveniently, is a consequence of ease of use.
Internal documentation enables software developers to understand the structure and implementation of a system. Internal documentation for complex modules must orient the developer to each source-code module by spelling out the answers to the the basic questions for that module. It should also lay out any complex algorithms involved, plus the flows of data and execution when they are not already obvious.
The need for internal documentation is a consequence of these requirements:
which themselves are are closely connected with
API documentation enables software developers to understand how to use the functions and data provided by a module without having to understand its implementation. The need for API documentation is a consequence of the reusability requirement. It also follows from extendibility and maintainability since module interface documentation makes it possible to determine whether a certain change needs to affect a certain module.
Rather than treating documentation as a product separate from the source code proper, it is preferable to make the source code as self-documenting as possible. This applies to all three kinds of documentation.
When documentation is a part of the source code itself, tools can be used to extract external-, module-, and API-documentation when external versions of these are needed.
These techniques lessen the role of traditional (externally-sourced) documentation, although of course we cannot expect them to remove it completely.
- ease of use
As a quality factor of source code, ease of use is the ease with which people of various backgrounds and qualifications can learn to use that source code (e.g. as a part of a library) and apply them to solve problems. For a library, this also covers the ease of installation, operation and monitoring.
- economy
The companion of timeliness, as a quality factor of source code, economy is the ability of a system to be completed on or below its assigned budget.
- efficiency
As a quality factor of source code, efficiency is the ability of the generated software system to place as few demands as possible on hardware resources, such as processor time, space occupied in internal and external memories, bandwidth used in communication devices.
- extendibility
As a quality factor of source code, extendibility is the ease of adapting it to changes of specification.
- functionality
As a quality factor of source code, functionality is the extent of possibilities provided by a system or library.
- integrity
As a quality factor of source code, integrity is the ability of the generated software systems to protect their various components (programs, data) against unauthorized access and modification.
- maintainability
Maintainability is almost synonymous with extendibility, except it extends that concept to include that the risk of adding bugs during maintenance is low or (preferrably) very low. The higher the maintainability, the lower the risk. Understandability, and modularity both add significantly to maintainability.
- maintenance
Software maintenance is the modification of software after its initial delivery.
- modularity
Modularity enhances both reusability, extendibility and testability. Its primary trait is that it reduces complexity by packaging source code into independent, logical bodies of functionality that can be independently tested outside of software systems in which they are used. The boundaries of source-code modules typically revolves around the management of a certain data type or of a small number of data types that work together. Once a module is tested and validated, it has shelf life. In other words, it usually does not need to be re-tested thereafter unless it has been changed.
Modularity also helps apply the DRY principle: Don’t Repeat Yourself. Reducing or eliminating redundancy in code helps code to be more reliable and less likely to incur bugs during changes of algorithm or data representation. Reason: changes to code that applies this principle need only be made in one place instead of multiple places in the code base.
- orient
verb, to find one’s position in relation to everything that is around or near you e.g. “The mountaineers found it hard to orient themselves in the fog.” In the context of documentation, it is orienting the reader mentally. This is done by establishing answers to The Basic Questions including grasping of (or supplying) applicable context, and connecting the answers to those questions to things he is already familiar with.
- orientation
- portability
As a quality factor of source code, portability is the ease of transferring generated software products to various hardware and software environments.
- problem domain
the area you are writing software for. For example, if you are writing firmware for a motorcycle-racing dashboard, the problem domains involved are
automotive electronics
motorcycles
motorcycle racing
- readability
When writing and documenting code, it is important to remember — to roughly quote one of the the fathers of Computer Science, Donald Knuth — that when you are writing source code, you are not just teaching the computer what to do, but also teaching other programmers how it works, not only for users of the API, but also future maintainers of your source code. Comments add information about what you were thinking when the code was written, and why you did things that way — subtleties about the design that cannot be conveyed by the source code alone.
Part of readability is that it consistently follows an established coding standard, such as the naming of variable and routines, and logic structured so that it is easy to follow.
- reliability
As a quality factor of source code, reliability is the degree to which features of the source code can be counted upon to do what they are supposed to do (according to their documentation), without introducing problems such as memory leaks or other bugs into the system. Reliability can probably be thought of as a combination of correctness and robustness.
- repairability
As a quality factor of source code, repairability is the ability to facilitate the repair of defects. Note: understandability plays a big role in this.
- reusability
As a quality factor of source code, reusability is the ability of source-code modules to serve for the construction of many different applications.
- robustness
As a quality factor of source code, robustness is the ability of the generated software system to react appropriately to abnormal conditions.
- testability
Testability is the ease with which a body of source code can be independently tested for correctness. Having tests written as part of creating software (TDD recommends tests be written before the source code being tested) builds up a list of tests, one by one, that eventually become a huge asset for that body of source code. Having a platform where such tests can be run after changes are made increases certainty of code correctness before software releases, as well as increasing certainty that no new buts are being introduced.
- timeliness
As a quality factor of source code, timeliness is the ability of the generated software system to be released when or before its users want it.
- understandability
As a quality factor of source code, understandability can be thought of as readability plus that extra depth of understanding that maintainers need before making changes to source code: it is full understanding of:
- for all software:
what the code does
- for modules:
how it fits into the design of that module
how it impacts that module’s data
- for higher-level code:
how it fits into the system design
how it impacts the system’s data, and therefore
how it impacts the rest of the system
- for firmware
- any changes to the CPU, such as
execution priority level (related to interrupts and exceptions)
OS threading context (normal, interrupts, exceptions)
OS coordination with other threads
how it impacts any peripheral devices that are involved
how it impacts any external chips that are involved
how it impacts any external devices that are involved
Understandability is inversely proportional to the time it takes for a programmer to reach full understanding of the code he is reading.
It can be argued that understandability enhances the following source-code quality factors:
- understanding
We speak about an understanding (of something) when we are talking about the knowledge that somebody has about a particular subject or situation. It can be considered a “mental package” upon which other learning can build upon.
- verifiability
As a quality factor of source code, verifiability is the ease of preparing acceptance procedures, especially test data, and procedures for detecting failures and tracing them to errors during the validation and operation phases.