Code Readability Guidelines
Code Readability Convention Definition:
Proper use of Comments along with File Page Readability including C# Regions and managing Dead Code
Code Readability Convention Justification:
Comments and regions should add value to understanding the intent of the underlying code.
They should not be overused or used to organize unrelated multiple Class responsibilities.
Commented out code, or dead code, should be removed before a type is checked into source control.
Code Readability Standards:
It is the responsibility of the Developer to create designs that clearly convey the intent of the developed code solution. The use of comments should be kept to an absolute minimum as the code itself should convey its intent.
The use of the double slash (//) and a comment to describe the next line which clearly states the intent is never a good practice
… It creates “Code Noise” and clutter with no added value.
Unless a documentation tool is being used by the enterprise to extract out triple slash (///) comments and descriptions all it does is add addition noise and clutter and is not a Best Practice
Regions should be used to encapsulate all Private Methods. This reduces code noise and clutter and goes to the intent of separating the Class responsibility from internal private dependencies.
Regions should not be used to group common methods as this is generally an indication of more than one responsibility within a single Class type. The unrelated methods need to be refactored into their own Class responsibility file.
Code commenting is a development strategy that is very useful during initial development. It allows for various solution concepts to be communicated and tested until the best solution idea is selected.
Commented out code should never be allowed to exist within a completed type as it add confusion and code noise to the underlying type
+A Comment Archiving Process
- Encapsulate the code in a named region at the very bottom of the Class
- Check in the commented out code
- Immediately check it out and delete the region
- Check in the clean code without the dead code region for consumption
The above process gives your code an archive version within the historical source control but ensures that anyone else viewing your code gets a clean, clutter free version
The following two tabs change content below.
I am a Principal Architect at Liquid Hub in the Philadelphia area specializing in Agile Practices as a Certified Scrum Master (CSM). I use Test Driven Development (TDD) and Acceptance Test Driven Development (ATDD) with Behavior Driven Development (BDD) as my bridge to Agile User Stories Acceptance Criteria in a Domain Driven Design (DDD) implementing true RESTful services