No matter the software product, it is important that the source code be easy to follow and maintain in the future.
We expect our software developers to act in a professional manner which includes producing source code that is easy to maintain.
Expectations on the readability of the source code is not a lot different from our expectations for other internal documents -- where we expect the author to use proper grammar, correct spelling, and appropriate organizational features of section headings, bullets, and spacing.
It is not feasible (or particularly valuable) to produce a standard set of coding guidelines that apply to all types of software products and development style that EPRI employs. If you are using a professional software developer, they will likely already have coding guidelines in place, and you should review these with the developer.
In cases where there are no coding guidelines, it would be appropriate to communicate your expectations to the developer. A basic set of high level expectations that is independent of development language is provided below. Additional detail in the coding guidelines may be appropriate depending on the nature of the project – in particular, if your team includes multiple developers from different organizations, it is important to make sure that everyone is working together to the same expectations.
There are many coding guidelines available in the industry, each suitable to a different purpose. Just like EPRI ascribes to the Chicago Manual of Style for technical reports, with additional commentary specific to EPRI, you may wish to start from a well-established set of coding guidelines.
An example of a programming language-agnostic coding standard can be found at https://12factor.net/.
High Level Coding Expectations
- Use comments liberally. Remember that you might be asked to modify this code a year from now and you will probably not remember what you did.
- Use appropriate white space to make the code easy to read. For example, include blank lines between functions and other major blocks of code. Indent nested logic. Include spaces between operators. This is no different than what you would do when writing a technical report.
- Avoid excessively long lines of code.
- Name variables in a clear and concise manner.
- Avoid doing anything ‘tricky’ or ‘non-standard’. If it is necessary to do something tricky, clearly explain it in the comments.
- Code defensively to avoid mistakes in the future. Explicitly type variables where possible, explicitly cast variables. Test all branch conditions (e.g. include ‘else’ and default cases’). Check for and report all unexpected errors. Validate input arguments.
Related Requirements
There are additional requirements that can be assessed during code reviews
- The software must not include any behavior that changes based on date, time of day, duration of use, or time since installation (e.g., “time bombs”), unless it is clearly disclosed in the end-user documentation.
- The software must not include any password functionality that persist passwords in plain-text.
- For export control reasons, it is recommended that the software avoid using any encryption capability, and instead rely on passwords and security provided by the operating system.
- The software must not include any “back-door” access