Design – Build – Run: Applied Practices and Principles for Production-Ready Software Development

22.4. Summary

This chapter looked at some of the practices to ensure that your code is maintainable and well-commented, and that it conforms to "best practices." It is important to get off to a good start so that you avoid issues later in the process.

The following are the key points to take away from this chapter:

• Prepare the solution. The solution should be well-outlined. If there are difficulties in doing this, it is probably because you haven't defined the design sufficiently. The solution outline is intended to:

  • Differentiate what is intended for production vs. testing

  • Provide a meaningful "at-a-glance" overview of the solution structure, projects, and components

• Switch on the profiler. Ensure that all the profiling tools are switched on and configured. When warnings are raised, they can be assessed, documented and suppressed as appropriate. There are many profiling categories and settings, each of which should be evaluated thoroughly.

• Use XML comments. XML comments are used to generate documentation from the code. There are many tags that can be used to generate a rich set of documentation, however the most commonly used tags include:

  • Summary

  • Remarks

  • Param

  • Returns

  • Exception

• Define and use commenting standards. A good set of commenting should be in place. The standards and guidelines should be adhered to throughout the project, including:

  • Describing the function or purpose of the code

  • Documenting the requirements

  • Commenting changes and changing the comments

  • Documenting non-conformance ...