So the conversation started today about a guy leaving our team and needing to knowledge transfer his part of the code base to the other team members. The lead programmer on the project told him to stop working on new development and start commenting his code so that the people coming in after him would understand what he had been doing.
Personally the first thing I do when opening a code base that I am not familiar with is to press CTRL-M, CTRL-O and start looking around. ( CTRL-M, CTRL-O is the default visual studio short cut for minimize all outlining. You get to see method declarations, and that is about it.) This will collapse blocks of comments so that they are not intrusive. I never re-expand them. The idea that you need comments for understanding code to me is a big red flag for bad code. I feel well named variables are much more intuitive to learning a new code base than using comments.
I have never sat down to learn an entire code base at one sitting. I am normally working on a small part or a bug fix and need to find something that is very specific. To that end a well named class/method/property is much more helpful with you use the ?Edit->Find? code parser than having to sort through and search all the comments for the set of information that you need.
Also, I am sure that almost everyone has opened a piece of code that had a form1, or class1 class right? Those names that MS graces us with are not supposed to stay named that. Here is the way you avoid this.
Step 1: Go to add class
Step 2: DON?T CLICK OK!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Step 3: Look down at the bottom of the dialog and type in something intuitive.
Step 4: Go drink something with an umbrella and retire to the happy place of understandable class name land.
To prove my point.
1: //This is a class that handles
2: //calculating tax for sales in
3: //several states
4: public class class1
5: {
6: //Calc sales total for a couple states
7: //AR - tax 9.5%
8: //NM - tax 5.5%
9: //TX - tax 8.5%
10: public decimal calc(decimal a, string n)
11: {
12: //The quick red fox jumped over the lazy brown dog.
13: //The quick red fox jumped over the lazy brown dog.
14: //The quick red fox jumped over the lazy brown dog.
15: //The quick red fox jumped over the lazy brown dog.
16: switch(n)
17: {
18: case "AR":
19: {
20: return a * 1.095;
21: }
22: break;
23: case "TX":
24: {
25: return a * 1.0875;
26: }
27: break;
28: case "NM":
29: {
30: return a * 1.055;
31: }
32: break;
33: }
34: }
35: }
versus my way
1: public class MultiStateSalesTaxCalculator
2: {
3: public decimal ARKANSAS_STATE_SALES_TAX = 0.095;
4: public decimal TEXAS_STATE_SALES_TAX = 0.095;
5: public decimal NEW_MEXICO_STATE_SALES_TAX = 0.095;
6:
7: public decimal CalculateSalesTotalWithTaxByState(decimal SubTotal, string stateAbreveation)
8: {
9: switch(stateAbreveation)
10: {
11: case "AR":
12: {
13: return SubTotal + ( SubTotal * ARKANSAS_STATE_SALES_TAX) ;
14: }
15: break;
16: case "TX":
17: {
18: return SubTotal + ( SubTotal * TEXAS_STATE_SALES_TAX);
19: }
20: break;
21: case "NM":
22: {
23: return SubTotal + ( SubTotal * NEW_MEXICO_STATE_SALES_TAX);
24: }
25: break;
26: }
27: }
28: }
71a08081-c681-4240-b5dc-96a59b6dd5a4|0|.0