Skip to content

Latest commit

 

History

History
41 lines (36 loc) · 3.91 KB

CppDocumentation.md

File metadata and controls

41 lines (36 loc) · 3.91 KB
Raw

(C++) documentation

Documentation is the process of adding non-compilable text to/next to your code.

Advice

  • Good code is its own best documentation [13]
  • Create good documentation [7]
  • Document all significant software elements [11]
  • Document each routine [15]
  • Create documentation as early as possible [12]
  • Keep comments close to the code they describe [5,14,16]
  • Document the interfaces [1]
  • Document the interfaces's assumptions [18]
  • Explicitly state conditions under which behavior is undefined [2]
  • The use of assert statements can help to document the assumptions you make when implementing your code [3]
  • If you break a general rule of style, document why you did so [4]
  • Comments are an important form of documentation
  • Take advantage of code documentation tools [17], for example Doxygen

References

  • [1] John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Chapter 2.6: 'Document the interfaces so that they are usable by others. Have at least one other developer review each interface'
  • [2] John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Chapter 2.6: 'Explicitly state conditions under which behavior is undefined'
  • [3] John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Chapter 2.6: 'The use of assert statements can help to document the assumptions you make when implementing your code
  • [4] Trevor Misfeldt, Gregory Bumgardner, Andrew Gray. The elements of C++ style. 2004. ISBN: 978-0-521-89308-4. Chapter 2.4, page 6: 'Document any deviations'
  • [5] Andrew Hunt, David Thomas. The Pragmatic Programmer: From Journeyman to Master. 1999. ISBN: 978-0-2016-1622-4. Tip 68: Build documentation in, don't bolt it on
  • [6] Andrew Hunt, David Thomas. The Pragmatic Programmer: From Journeyman to Master. 1999. ISBN: 978-0-2016-1622-4. Tip 20: Keep knowledge in plain text
  • [7] Steve McConnell. Rapid Development. 1997. ISBN: 978-1-55615-900-8. Page 534: Create good documentation
  • [8] Trevor Misfeldt, Andrew Gray, Trevor Misfeldt. The Elements of C++ Style. 2004. ISBN: 978-0-521-89308-4. Chapter 32: Document your software interface for those who must use it
  • [9] Trevor Misfeldt, Andrew Gray, Trevor Misfeldt. The Elements of C++ Style. 2004. ISBN: 978-0-521-89308-4. Chapter 33: Document your implementation for those who must maintain it
  • [10] Trevor Misfeldt, Andrew Gray, Trevor Misfeldt. The Elements of C++ Style. 2004. ISBN: 978-0-521-89308-4. Chapter 34: Keep your comments and code synchronized
  • [11] Trevor Misfeldt, Andrew Gray, Trevor Misfeldt. The Elements of C++ Style. 2004. ISBN: 978-0-521-89308-4. Chapter 37: Document all significant software elements
  • [12] Trevor Misfeldt, Andrew Gray, Trevor Misfeldt. The Elements of C++ Style. 2004. ISBN: 978-0-521-89308-4. Chapter 38: Document software elements as early as possible
  • [13] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 817: 'Good code is its own best documentation'
  • [14] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 806: 'Keep comments close to the code they describe'
  • [15] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 806: 'Document each routine in one or two sentences at the top of the routine'.
  • [16] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 806: 'Document parameters where they are declared'
  • [17] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 807: 'Take advantage of code documentation utilities such as Javadoc'
  • [18] Steve McConnell. Code complete. 2004. ISBN: 978-0-7356-1967-8. Pag 808: 'Document interface assumptions'