BLACKWOOD DESIGNS Quality Software Design SOFTWARE DESIGN GUIDES AUTHOR RANDALL MAAS OVERVIEW This guide describes the design of high quality software for embedded systems. The intent is to promote well-founded, justified designs and confidence in their operation. It provides guides, checklists and templates. BENEFITS Improve the quality of source code: its maintainability, testability, etc. Prevent potential defects Smoother, shorter design / release cycles Better software products TEMPLATES Design documentation templates Design review checklists Software Risk Analysis Templates Bug reporting template Coding Style guides for C and Java Bug defect type classification Code review checklists Code quality rubric Copyright © 2003-2018 Blackwood Designs, LLC. All rights reserved. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose, without the express written permission FILE : G:\My Documents\BD4 SW Design Documents\guide-quality software\BD4 Quality of Blackwood Designs. Software Guide.doc RANDALL MAAS has spent decades in Washington and Minnesota. He consults in embedded systems development, especially medical devices. Before that he did a lot of other things… like everyone else in the software industry. He is also interested in geophysical models, formal semantics, model theory and compilers. You can contact him at [email protected]. LinkedIn: http://www.linkedin.com/pub/randall-maas/9/838/8b1 Q U A L I T Y S O F T W A R E D ESIGN · 2 0 1 8 . 0 8 . 1 6 ii PREFACE ............................................................................................................................1 1. ORGANIZATION OF THIS DOCUMENT .....................................................................................1 SPECIFICATIONS .................................................................................................................5 OVERVIEW OF SOFTWARE DESIGN QUALITY .......................................................................7 2. OVERVIEW .....................................................................................................................7 3. SOFTWARE QUALITY OVERVIEW ..........................................................................................8 4. A TIP ON STAFFING ......................................................................................................... 10 5. REFERENCES AND RESOURCES ........................................................................................... 10 PROCESS .......................................................................................................................... 11 6. PROCESS ..................................................................................................................... 11 7. THE ROLE OF CERTIFYING STANDARDS ................................................................................. 14 8. SOFTWARE DEVELOPMENT PLAN ........................................................................................ 18 9. RISK ANALYSIS .............................................................................................................. 18 10. TERMS RELATED TO TESTING, VERIFICATION, AND VALIDATION............................................... 19 11. REFERENCES AND RESOURCES ......................................................................................... 20 REQUIREMENTS CHECKLISTS ............................................................................................ 23 12. OVERVIEW OF WELL WRITTEN REQUIREMENTS .................................................................... 23 13. REQUIREMENTS REVIEW CHECKLIST .................................................................................. 24 SOFTWARE RISK ANALYSIS ............................................................................................... 27 14. SOFTWARE REQUIREMENTS RISK ANALYSIS ........................................................................ 27 15. REFERENCE DOCUMENTS ............................................................................................... 31 SOFTWARE DESIGN & DOCUMENTATION ......................................................................... 33 DESIGN OVERVIEW & WRITING TIPS ................................................................................. 35 16. THE ROLE AND CHARACTERISTICS OF DESIGN DOCUMENTATION ............................................... 35 17. DOCUMENTATION ORGANIZATION ................................................................................... 36 17.1.1 TIPS FOR GETTING THE DEFINITIONS FOR STANDARDS TERMS ................................................... 38 17.2.1 THE ACRONYMS AND GLOSSARY ........................................................................................ 38 17.2.2 THE REFERENCES, RESOURCES AND SUGGESTED READING ...................................................... 39 Q U A L I T Y S O F T W A R E D ESIGN · 2 0 1 8 . 0 8 . 1 6 iii 17.2.3 FILES ............................................................................................................................. 39 18. REFERENCES AND RESOURCES ......................................................................................... 40 HIGH-LEVEL DESIGN TEMPLATE ........................................................................................ 41 19. BASIC OUTLINE ............................................................................................................ 41 20. DIVISION INTO MODULES ............................................................................................... 44 21. REFERENCES AND RESOURCES ......................................................................................... 46 SOFTWARE ARCHITECTURE RISK ANALYSIS ....................................................................... 47 22. SOFTWARE ARCHITECTURE RISK ANALYSIS ......................................................................... 47 DETAILED DESIGN ............................................................................................................ 51 23. DIAGRAMS AND DESIGN DECOMPOSITION INTO MODULES .................................................... 51 24. ORGANIZATION ........................................................................................................... 54 25. REFERENCE SUBSYSTEM DETAILED DESIGNS......................................................................... 55 25.2.1 DIVISION INTO MODULES .................................................................................................. 58 25.2.2 DMA FOR GATHERING SAMPLED LINEAR INPUTS AND LINEAR OUTPUTS ..................................... 58 25.3.1 DMA FOR COMMUNICATION ............................................................................................. 59 25.4.1 DMA FOR STORAGE COMMUNICATION ............................................................................... 60 26. FIRMWARE UNIT AND SUBSYSTEM TEST ............................................................................. 61 27. REFERENCES AND RESOURCES ......................................................................................... 64 COMMUNICATION PROTOCOL TEMPLATE ........................................................................ 66 28. COMMUNICATION PROTOCOL OUTLINE ............................................................................. 66 29. INTERACTIONS ............................................................................................................ 67 30. THE DIFFERENT TRANSPORT MECHANISMS .......................................................................... 68 31. TIMING CONFIGURATION AND CONNECTION PARAMETERS ..................................................... 70 32. MESSAGE FORMATS ..................................................................................................... 70 32.1.1 COMMAND ..................................................................................................................... 71 32.1.2 RESPONSE RESULT ........................................................................................................... 71 33. REFERENCES AND RESOURCES ......................................................................................... 72 SOFTWARE MODULE DOCUMENTATION TEMPLATE .......................................................... 73 34. DETAILED DESIGN OUTLINE ............................................................................................ 73 35. THE OVERVIEW SECTION ................................................................................................ 73 36. THE SOFTWARE INTERFACE DOCUMENTATION .................................................................... 74 FOO_T STRUCT REFERENCE ............................................................................................................. 76 FOO CLASS REFERENCE ................................................................................................................... 77 37. THE DETAILED DESIGN SECTION ....................................................................................... 80 Q U A L I T Y S O F T W A R E D ESIGN · 2 0 1 8 . 0 8 . 1 6 iv 38. CONFIGURATION INTERFACE ........................................................................................... 82 39. THE TEST SECTION ........................................................................................................ 82 40. REFERENCES AND RESOURCES ........................................................................................